4

I came to a point where it is absolutely necessary to have some kind of documentation about my product. So some sort of help or user manual for customers, because i want to reduce the number of emails.

So I was looking for something that allows me to:

  • export to PDF

  • handles translations (possibly by giving the translators limited access?)

  • implementation online, on my webpage/server, ...

  • (not a condition) integratable in wordpress

Something like Manula for example. Manula is not free, which is not a problem, but is rather expensive, which does represent a small problem. Is there anything similar and perhaps something you would recommend?

What do you use?

  • 1
    Could you somehow specify the intended quality of the respective emitted document formats, please? Something that is well-readable on screen (with internal links etc.) can often be converted to PDF somehow, but the resulting document usually looks like what it is, basically a webpage forced into print paper. Conversely, well-layouted and structured PDF documents often come across as unwieldy when their contents and structure is directly transferred to something like HTML. (I'm thinking of my experiences with DocBook and a few other multi-format generators here.) – O. R. Mapper Feb 14 '17 at 19:56
  • @O.R.Mapper Thanks for pointing that out. It's a shame I haven't really thought about that. Ideally I would like to have something that is well-readable on screen and at the same time well-layouted in a PDF document. I guess that is not an option. If I have to decide I would rather have things well readable and user friendly on screen at a cost of a slightly weaker layout of a PDF document. – skrat Feb 14 '17 at 20:19
  • The nice thing about Sphinx is that, as each document type is generated rather than converted, it is possible to have several well laid out formats from a single source - @Mawg has a point of course, hence RTFM, but you can't RTFM when there is no manual. – Steve Barnes Feb 18 '17 at 7:34
2

Personally I can strongly recommend Sphinx Document Generator:

  • Free, Gratis & Open Source
  • Cross platform
  • One set of base files, in ReStructuredText format which are easily version controllable.
  • Simple inclusion of screenshots, etc.
  • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text.
  • Mechanisms for Internationalisation where the text words & phrases are translated rather than the entire document.
  • Multiple styles
  • Automatic generation of Table of Contents, Index, Cross References, Glossary, Citations, etc.
  • Multi-language & extensible syntax highlighting
  • Used by 100s of projects so large user base and lots of support.

Notes on internationalisation

To expand on the internationalisation, often called I18N because it is a lot less to type, Sphinx uses the same tried and tested that the majority of open source projects have used since gettext was released in 1995.

You use a Message Catalogue Builder tool within Sphinx to produce a set of pot files which are message catalogues, strictly portable object templates, containing words, phrases & paragraphs from your original document. Copies of these go off to the translator(s) for the desired language(s) who use a tool such as Pootle or poedit to provide their individual translations and return them as portable object, .po files. Note that this can all be done collaboratively using services such as Transfex.

These .po files are run through the gettext msgfmt tool to produce message objects, .mo files. Once these have been added into your project, at a language specific location, you can run Sphinx again specifying the output language and your documents will be output in the requested language. Any missing translations will remain as the original text.

One of the big advantages of this approach is that if you make changes to your documents, as inevitably happens, the tool chain shows the translator(s) what is already translated and they only have to update the new/changed items and any incorrect items. Another is that you never have to maintain multiple copies of your source document, (usually this ends up as one per language), just of your translation files.

Sphinx Translation Workflow

Workflow courtsey of the Sphinx web site, stick figure originally from XKCD commic

Diagrams & Charts

If your documentation includes diagrams with text you can use one of a number of Sphinx extensions, such as the Graphviz extensions to generate the diagrams automatically, in the case of Graphviz using the dot language, or you can Generate diagrams & charts by embedding some python in your document which will allow your diagrams & charts to be automatically updated at the time of building your document, you can even overlay text on images & photographs this way. The nice things with this is that you are embedding some text that produces the chart, etc., rather than embedding them directly which is better for both version control & internationalisation. There are also extensions for Google Charts & Maps

  • Do you happen to know anything about the GUI of Sphinx? My question is: If I let the translators in admin pages: will they know what to do or do they need at least basics in programming? Have you got any experience in that? – skrat Feb 17 '17 at 18:29
  • 1
    @skrat You do not have to give the translators any change access at all & they need no programming experience. I have expanded my answer to give my understanding of the process. – Steve Barnes Feb 18 '17 at 7:07
  • 1
    @skrat You can also use the same basic tools and workflow in your code to internationalise your software, you basically tag strings in place, they are extracted to the pot file, etc. but the tags are also macros to calls to translate which will pick up the translations from the .mo for the current language if it is present. This even allows you, once you have your first translation working, to add languages without rebuilding your code see gnu.org/software/gettext/manual/html_node/… for languages. – Steve Barnes Feb 18 '17 at 7:49
1

Libre Offfice's "writer" will let you generate both to HTML and PDF.

When the time comes, you can easily make your documents ready for the Web via Writer's HTML export feature, or you can automatically publish to a wiki in MediaWiki format.

If you need to be sure that what you publish is viewable and looks exactly on every kind of reading device and platform, the "Export as PDF" (.pdf) feature generates a .pdf file. LibreOffice's PDF export feature provides a large number of formatting and security options, enabling you to cater to many different constraints, including production of ISO-standard PDF/A files.

  • 1
    Ok, but how would you make the documenation/help multilingual with libre? – skrat Feb 15 '17 at 20:56
1

Lately I've been seeing Read the Docs being used in a lot of (OS) projects. As far as I can tell it's mainly aimed at code documentation, not sure if that fits your need.

Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. We support webhooks so your docs get built when you commit code. There's also support for versioning so you can build docs from tags and branches of your code in your repository.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.