6

Background

Looking to unify technical documentation, bridging computer- and user-generated content, using open source tools. The goal is to write (or generate) content in an output agnostic file format, which is then transformed into a final document. The figure below helps illustrate how the overall pieces connect.

Documentation architecture

The solution should be operating system independent.

Output Features

The final document must include:

  • Tables
  • Figures
  • Code Snippets
  • Auto-numbered captions (for tables, figures, and code snippets)
  • Cross-references (hyperlinked to tables, figures, and bibliographic citations)
  • Headings (up to seven levels; 1., 1.1., ..., 1.1.1.1.1.1.1.)
  • Appendices (up to seven levels; A., A.1, ..., A.1.1.1.1.1.1.)
  • Auto-numbered headings and appendices
  • Table of Contents (hyperlinked)
  • List of Tables (hyperlinked)
  • List of Figures (hyperlinked)
  • Bibliography (books, articles, journals, whitepapers, websites [hyperlinked])
    • Variety of formats (APA, Chicago, IEEE, etc.)

Most importantly, stylization (through templates or coding) should be possible so that all the documentation can be re-generated with a new look and feel. ConTeXt, for example, excels at this.

Markdown and Pandoc offers much of this functionality, though I'm not sure if it handles cross-references, auto-captions, bibliographies, and code snippets.

Input Features

  • Cross-document variables (e.g., a server name is documented once, but referenced by application architecture and software requirements specifications).
  • Browser-based WYSIWYG editor (possibly Confluence)
    • Table editor
    • Transclusion (embedded excerpts to help single-source content)
    • Collaborative (ideally, real-time)
    • Revisions
    • Markdown (ability to view source, but predominately used like a modern word processor)
  • Computer-generated content is transformed into Markdown format:
    • Source code documentation (package descriptions, no hyperlinked content necessary); Javadocs, Doxygen, etc.
    • SNMP (names and IP addresses of network devices)
    • Diagrams (entity-relationships, UML, GraphViz, etc.)
      • Ideally, JPG, PNG, and SVG images could be imported
    • List of database surrogate keys and descriptions (dumped from database)

Questions

Is it even possible to generate a high-quality technical document that includes such a wide variety of artifacts using only Markdown as the source content?

Here are the pieces that I'd appreciate recommendations or suggestions on:

  • Including source code (e.g., Javadoc/Doxygen -> Markdown)
  • Possibility to reformat various *nix command outputs to Markdown (nmap, traceroute, ls, tree, df, SNMP output, etc.); the translation could be massaged using awk and sed, for example.
  • WYSIWYG editor (FOSS alternatives to Confluence)
  • FOSS that can handle churning the output features from Markdown source into the desired output formats (PDF definitely and MS Word optionally).
    • If Pandoc/ConTeXt cannot accomplish this feat, what can?
  • Software and/or data formats (e.g., Markdown, YAML) for integrating bibliographies and cross-references such that the document generator (e.g., ConTeXt) can use them (e.g., RStudio)?

If there is a single software package that brings together all these features, I'd be keen to know that, too.

Related

Related questions include:

Software

Specifications

1

I am reasonably certain that will a little work you could put something very like what you are describing using Sphinx Docs. The one area that you might have problems with is Real Time Collaborative Editing.

  • Base format is Restructured Text, (rather than markdown), but inputs can be in markdown.
  • Multiple output formats
  • Multiple input sources including source code, wiki, on-line, etc.
  • Can invoke and post process multiple tools during build process
  • Cross Platform
  • Open Source
  • Produces really good looking documentation
  • All of your requested output features available
  • Templates - Yes
  • Produce multiple output format documents - Yes
  • Syntax highlighting of code fragments in multiple languages thanks to Pygments.
  • Extensive cross-references: semantic markup and automatic links for functions, classes, citations, glossary terms and similar pieces of information.
  • Good internationalisation support using gettext.
  • Extensible and actively developed.
  • Thank you. Looks like there's an XML builder, which could be used with ConTeXt. as well as what appears to be a ConTeXt builder extension. – Dave Jarvis Apr 19 '16 at 15:41
  • In an example with an appendix, the heading numbers don't use letters. This could have been an oversight/misconfiguration of the engine used to render the PDF, though. – Dave Jarvis Apr 19 '16 at 15:49
  • I have just run some tests based on docutils.sourceforge.net/docs/ref/rst/… and those work fine for auto-enumerated - even the Roman numerals. – Steve Barnes Apr 20 '16 at 5:57

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.