From The Document Foundation Wiki
Jump to navigation Jump to search

Basic thoughts

So, to make sure every body is listened, I add the links the the mail archives concerning this topic

Uwe Fisher (author of OOo help) blogged about our effort, interesting: [1]

Help is different from documentation. It's a functional description of the items in the UI. It doesn't give you the path to achieve a task, it gives a description of a functionality. This means that this help file is light, easy to translate, has all the basic needed information to know what the function does. Hence alos the extended tips.

That allow:

  • to distribute the file along with the product
  • to get accurate information on the functionality with each version
  • to provide a low cost access to localization and information

Now I understand that:

  • help files are difficult to access to developers and this is not their job to write documentation
  • help files need to be enhanced and get a better description whatever the language
  • documentation team should have access to it and makes it more documentation like and improves its quality
  • it's impossible to achieve a good localization on the wiki, it's simply a nightmare to handle and keep up to date,
  • though localization team is responsible of its translation as part of the product.

What I propose :

  • get the file on the wiki
  • let the documentation team takes care of the file with the developer's input
  • we should take care to have [I don't know how it's technically feasible however]:
    • a simple version very descriptive like the help file is currently that will still be delivered along with the product, then it needs to be updated frequently
    • have a more documented version, containing more example or how-to achieve task that will stay on the wiki and will not be delivered with the product
  • have both files uploaded on Pootle:
    • the first light one would be the one that all localization team would have to take care to deliver the product
    • the more documented one would be optional and may also be translated by documentation team on the wiki


Discussion of single aspects

Localhelp / Local Caching / Wikihelp

Have you thought of totally dropping built in localhelp but offer local html files instead with a modified browser which opens the local html file if no internet is available? Nino 2013-04-17T13:44:59 (UTC)

It's currently what we have, help files are converted from xml to html and displayed in an internal LO browser :) Sophi

Research into offline help systems

The options for an open source cross-platform help system are limited.

Perhaps the most straightforward method would be to dump from MW to static HTML.

MWoffliner and Wiki2html seem like appropriate tools. MWoffliner does have heavy dependencies: nodejs, but also a redis server!

Kiwix is a tool for viewing offline MW content.

DocBook is another popular help system. Unfortunately the conversion situation does not look very good: (no export for latest DocBook 5 version) (proposal for a new extension)

Sphinx is a solution with maybe a bit more promise. However, it uses a format called reStructuredText so we would have to run Pandoc to convert from MW to rST.

This is an interesting read on why Blender decided to switch from MW to Sphinx: Beluga (talk) 2015-09-22T09:50:04 (UTC)

Just bumped into these: Beluga (talk) 2015-10-07T12:33:25 (UTC)

Inconsistency in bug reporting guidelines

Hi guys

I noticed a bit of an inconsistency that might make it very confusing for people wanting to help:

In Development/Wikihelp#Feedback_and_Bugs, people are told to either use Redmine for technical bug reports and the localisation mailing list for content/feature/improvement reports. On the other hand, in Development/Wikihelp#The_Timeline, we are told to use Bugzilla and assign the report to Kendy!

Could someone make it clearer? I assume the preferred method is the first one, according to the comment at the end of the section.

Cheers! Chtfn (talk) 2014-11-07T02:39:10 (UTC)


So the docs are still uneditable? Nemo bis (talk) 2016-08-14T11:06:37 (UTC)

Same question. This page says "Only the English pages will be editable." But once you're there, you can only log in (there is no create account capability, oddly), and the credentials don't work. So how do we edit Urhixidur (talk) 2017-03-29T16:42:48 (UTC)