Project

General

Profile

Task #2394

master ticket for new documentation approach

Added by Mike Saunders about 2 months ago. Updated 11 days ago.

Status:
New
Priority:
Normal
Target version:
Team - Q1/2018
Start date:
Due date:
% Done:

0%

Estimated time:

Description

GOALS

  • Bring all help content together
  • Use the XHP help as the primary source of information
  • Make it easier for end users to contribute fixes and new content
  • Retire old tools like the HelpAuthoring extension (buggy and generates bad XHP)

STEPS

  • Remove offline (F1 key) built-in help tool in LO 6.0 (Kendy is working on a patch for this)
  • For LO 6.0, create help packages (Olivier)
  • From LO 6.0 onwards, offline and online help will be displayed in the user's browser, for better rendering
  • Update XHP spec for additional sections, so that some can be used in online help, and others for books (Mike and Olivier)
  • For LO 6.1, implement an "Edit" button in the online help, along with login credentials and a user-friendly WYSIWYG editor that saves as XHP (Mike to work on this)
  • Then implement the workflow: use Git as ultimate source of XHP, and Gerrit for submissions of help content changes. When the user saves his/her changes, the editor creates a commit after submission, which goes to Gerrit for review by the docs team. (Maybe add a bot to do XML verification before integration?) (Mike to work on this)
  • Long-term goal for LO 6.2: extend XHP for merging with the books (eg sections or markup) - maybe even generate new guidebooks from that content. Add an editor preview mode - eg show how changes will look in the context of other help sections or a book
  • Another long-term goal: add "Search Ask" bar to online help interface

TRACKING PROGRESS

  • Call on November 14th or 15th to discuss progress and ideas
  • Mike to join ESC calls
editor_progress_1.png (305 KB) editor_progress_1.png Mike Saunders, 2017-12-07 16:26
editor_progress_2.png (282 KB) editor_progress_2.png Mike Saunders, 2017-12-07 16:26
editor_progress_3.png (614 KB) editor_progress_3.png Mike Saunders, 2017-12-07 16:26
2159
2160
2161

History

#3 Updated by Mike Saunders about 1 month ago

So here's an update on the XML editor situation. Buovjaga has helpfully pointed out a couple of options:

I'm investigating the latter now, as I believe WYSIWYG is important for encouraging people to work on the docs, without having to know what's going on with XML in the background.

Also waiting to hear from Jean Spiteri regarding his ideas, but haven't heard from him for a few weeks now.

#4 Updated by Mike Saunders 11 days ago

Still haven't heard back from Jean Spiteri, and ProseMirror turns out to be immensely complicated (the developers even describe it as a toolkit for creating editors, rather than an editor itself). So I've been working on an editing system that's built upon the new web help viewer that Olivier has created: https://helponline.libreoffice.org

First I added the "contenteditable" attribute to the "DisplayArea" div. This makes the div editable, but there's no immediate way to store the changes

So I added a form and a submit button. "DisplayArea" isn't part of a form, but I used some JavaScript so that when the Save button from the form is clicked, the "DisplayArea" content is copied into a hidden form field, which is then sent to a PHP script for processing. See how it works in the three screenshots attached to the ticket:

  • editor_progress_1.png - "DisplayArea" with "contenteditable" attribute, and a Save button which sends the data to process.php
  • editor_progress_2.png - The output of process.php, a one-line script which just shows the data passed to it. Here's where we have a limitation...
  • editor_progress_3.png - The data being passed (.innerHTML from the "DisplayArea" div) is the HTML after the stylesheet transformation, whereas we want the XML.

So that's where we stand right now. It may be possible to get the XML using different JavaScript, or we may need another approach.

Also available in: Atom PDF