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.
The solution should be operating system independent.
The final document must include:
- 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., ..., 126.96.36.199.1.1.1.)
- Appendices (up to seven levels; A., A.1, ..., A.188.8.131.52.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.
- 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)
- 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)
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 (
df, SNMP output, etc.); the translation could be massaged using
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 questions include: