%% Last Updated: - [[2021-02-28]] - [[2021-02-26]] %% Literature notes from the book [[Modern Technical Writing]]. [[Writing]] [[Principle of Atomicity]] [[Know your audience#^ca2813]] [[Technical Writing]] principles: 1. Create good product documentation 2. Record changes in a product (changelog, release notes) 3. Setting up frameworks to facilitate contribution - Store content directly in an XML-based language. Keep content separate from other application code. - Consider using a lightweight markup language so people don't have to write in XML. - Git for version control and public, but managed, writing flows. Bonus: developers like it, so this is a way to get them to write. - Add a README.md with instructions on how to contribute 4. Publish frequently 5. Store doco in the same repository as source code - Reduced barrier to entry for devs - Let doco and code versions stay in sync - Reduce PR submission policies 6. Don't create duplicate content - Modularize and link to relevant steps rather than repeating yourself, so you only have to update documentation in one place. - use conditional text if available (AsciiDoc and RST) 7. Make static websites - Reduce resources required by letting web server just serve pages rather than having to generate them dynamically 8. Add search 9. Track documentation metrics 10. Be aware of localization costs 11. Treat everything as a working draft that should be continuously revised. Questions that product documentation in [[Technical Writing]] should answer: - What is this product? - Why should I want it? - How does it fit into a broader ecosystem? - What are its prerequisites? - Where/how can I acquire this product? - How do I install it? - What are its basic configuration options? - What does a single end-to-end use case look like? (Happy path) - Good technical writing - is jargon-free - is marketing-free - uses headers, tables, lists, diagrams, and screenshots to break up paragraphs of text Formatting - **bold** for UI elements - _italics_ for emphasis - `monospace` for code, commands, and filepaths. [[XML]]-based languages - [[XHTML]] - [[DocBook]] - [[DITA]] [[Markup languages]] - [[obsidian-playbook/Using Obsidian/02 Making Notes in Obsidian/Markdown]] - most widely usedd - cleanest syntax - con: limited set of features and no defined standard (ex: Github-flavored Markdown, MultiMarkdown, Markdown Extra, CommonMark) - somewhat futureproof - [[reStructuredText]] (RST) - Python - standardized implementation - more feature-rich than md (tables, footnotes, directives for code and other content blocks, conditional text through `only::`) <!--ID: 1614530440548--> - [[AsciiDoc]] - semantically equivalent to DocBook (XML-based language) - conditional text through conditional inclusion macros - [[LaTeX]] - it's a markup language, but it's NOT lightweight. - mainly used in academia Managing remote repos for content - [[BitBucket]] - [[Stash]] - [[GitHub]] - UIs: git-gui (default), Atlassian SourceTree, GitHub Desktop [[Static website generator]]s - [[Sphinx]] - [[Jekyll]] - [[Hugo]] - [[AsciiDoc]] - [[Middleman]] - [[Metalsmith]] - [[MkDocs]] - [[Hexo]] Search: Algolia Convert between markup formats: [[Pandoc]] ## Also modified - [[Publishing and distribution]] - [[Software Development]] - [[Git]] ## Citation Etter, A. (2016). _Modern technical writing: An introduction to software documentation_.