Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Is there a way to write documentation in a WYSIWYG editor which can then export into HTML, WORD and PDF and keep copies synchronized?

This documentation are mostly technical notes and some contextual help for some softwares so they must contain images and some styling, they are not programmer's documentation (API list or functions list) for which probably a program like Javadoc or Doxygen would be the best choice.

For example how do companies with hundreds different software lines and thousands of programmers deal with this?

I have several solutions but they all seem lacking in some aspect:

  • Latex/Tex : very good pdf and html export, not very user friendly and no full-blown WYSIWYG editor available.

  • LibreOffice/OpenOffice : full blown WYSIWYG editor however html export not so good (need to edit manually exported html which needs to be maintained separately )

  • Mediawiki or any other wiki : could be keeping documentation in wikitext format, so html is automatically generated, pdf exportation is quite good with many available plugins. Again however need some formation for the staff to use it and need to setup a server for this.

Notice I'm not asking for software A vs software B, I'm asking for general advice, big companies procedures for documentation and yes some software product names if available.

share|improve this question

closed as off-topic by gnat, GlenH7, MichaelT, tcrosley, Giorgio Nov 6 '13 at 19:24

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – gnat, GlenH7, MichaelT, tcrosley, Giorgio
If this question can be reworded to fit the rules in the help center, please edit the question.

    
Why do you need these three file formats? Just stick with an online documentation (e.g., Wiki). This is how most big software companies I know do it. –  sfat Nov 5 '13 at 8:36
    
html is needed for the online website, pdf is usually sent via mail or inside the installation cd, word or similar is because staff is used to use word or similar for writing, I cannot tell them to start coding latex or html. If you could expand your "how most big software companies do it" into an answer I'd appreciate –  dendini Nov 5 '13 at 8:52
    
Sounds like you answer yourself right here. You'll need to use Word since you state this as a requriement. However, there's LaTeX wysiwyg editors such as lyx: lyx.org –  iveqy Nov 5 '13 at 10:12
2  
To keep documentation aligned, you need to have one format that is the master source and from which all others can be generated. –  Bart van Ingen Schenau Nov 5 '13 at 11:12

3 Answers 3

Pandoc can handle all of those formats and more. It takes markdown and produces html, pdf, plaintext, word (or at least odt) etc.

EDIT: As a wiki-like solution there is gitit which uses pandoc as the backend and can export to different types.

share|improve this answer

I use Sphinx: http://sphinx-doc.org/

You write your docs in reStructuredText, and Sphinx can produce several output formats.

Quote from the Sphinx site:

  • Output formats: HTML (including Windows HTML Help), LaTeX (for printable PDF versions), Texinfo, manual pages, plain text
  • Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information
  • Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children
  • Automatic indices: general index as well as a language-specific module indices
  • Code handling: automatic highlighting using the Pygments highlighter
  • Extensions: automatic testing of code snippets, inclusion of docstrings from Python modules (API docs), and more
share|improve this answer
    
Wow Sphinx seems to meet most criterias, only missing bit is support for Java but quite a good start.. thank you –  dendini Nov 5 '13 at 13:16
    
The downside is, that you have to teach your staff to write reStructuredText. –  sfat Nov 5 '13 at 13:25
    
On one hand, yes. On the other hand, I'd say that this is true for most technologies that have built-in support to output multiple formats. At least Markdown or reStructuredText are easier to learn than LaTeX or XML. (Maybe there's even a Word-like editor that can save Markdown or reStructuredText? I don't know if one exists, but who knows?) –  Christian Specht Nov 5 '13 at 13:42

In past projects I used to maintain docbook code (XML) directly: http://www.docbook.org/.

DocBook can be transformed to virtually anything (PDF, HTML, Ms-Word) using XSLT, XSL-FO, POI, ...

The next step would be to generate parts of the DocBook code from parts of your code or your project structure.

share|improve this answer
    
I'm not convinced by the XML language but I'll take it into account.. Actually there are some editors for docbook like xmlmind.com/xmleditor/ which might make it a viable solution. –  dendini Nov 5 '13 at 13:19
    
True: it's not very attractive to manually maintain XML, this is why I only use it as an itermediate model. I usually have a generator toolchain that will transform data from a lot of sources (Java-Files, XML-Config-Files, Property-Files, Annotations, Plain text files, SQL-Files, UML-Models, etc...) into one big docbook XML model. And from that I produce the final formats (PDF, Word, HTML (single/multi page), ...). –  mwhs Nov 5 '13 at 13:23

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