We seek to surprise and delight developers. - devs don't like to write docs (or code, for that matter) - code is structured by nature - can we leverage the structure of code to produce docs? (spoiler: YES)
- Instructions (Howto, tutorial, )
- Reference (Release notes, API guides)
- Description (Sequence diagrams, RFC, Architecture guides, WhitePapers )
- Persuasion (Whitepapers, Data sheets, Benchmarks, demos)
... and chatter.
- Slack vs Gitter
- Discourse vs Discord
- GDocs vs Confluence
- Confluence vs Sphinx
- Markdown vs HTML
- rST vs Asciidoc (MyST)
- google docs vs Word
- HTML vs PDF
- ePub vs MOBI
- Confluence vs WikiMedia (somebody shoot me)
- The `touch` pattern (reverse breadcrumb)
- Copy on write (how to avoid the /var/log/syslog black hole)
- Federate search, not editors
- the dream of literal programming
- Doxygen, comments as code
- docutils and rST
- templates and semantic markup
- cucumber and gherkin (feature files)
- One file or many?
- One author or many?
- On version or many?
- On cycle or many?
- One content owner or many?
- Meta data (golden signals, SEO, dependencies)
- Context (set the stage with a human touch)
- Details (where the compiler is the source of truth)
- academic, loose structure, DIY
- Content is close to the source, but static
- Structured layout
- Compiler binds symbols and meaning
- Dynamic and elastic
- rST abstracts the functional parts
- Jinja abstracts the layout
- Python Sphinx
- Typo3 CMS
- DITAA
- Avoid Google Search for help on Sphinx: (the oldest, least useful results appear first) [I like the coderefinery tutorial](https://coderefinery.github.io/sphinx-lesson/toctree/)
- Sphinx Themes
- The
touchpattern- Federate search, not editors
- Track readers if you can, downloads if you must
- (Thanks to Diataxis)