Software tools for creating awesome engineering documentation

---

---

AI Summary

• Joining an Engineering Project Over a Decade Ago
  • Excitement and daunting feeling due to extensive documentation.
  • Documentation was hard to search and update.
  • Relied on word processing applications and hard copies for comments.
• Current Documentation Practices
  • Many organizations still use non-searchable, hard-to-update documentation.
  • New software tools are improving documentation creation and collaboration.
• Software Tools for Documentation
  • Suggests using open standards like Markdown, CSV, and JSON.
  • Tools and frameworks enhance document accessibility.
• Markdown and Related Tools
  • Simple syntax for adding various elements to documents.
  • Markdown preview enhanced viewer in VS Code.
  • HTML, CSS, and JavaScript can render Markdown files with additional information.
  • Mermaid.js for flowcharts, sequence, Gantt charts, class diagrams, etc.
  • MathJAX for rendering equations.
  • D3JS and Vega for creating dynamic visuals and graphs.
  • JS sequence diagrams for UML sequence diagrams.
  • Wavedrom for digital timing diagrams.
• Documenting with Markdown
  • Easy to add information and create a table of contents.
  • Can generate an HTML webpage from a Markdown file.
  • Ability to print the page as a PDF.
• Tracking Changes with Version Control
  • Git for tracking documentation changes.
  • Github, Gitlab, Bitbucket for storing Git-backed directories.
  • Publishing repository as a webpage using Github Pages.
• Static Site Generators
  • Control over HTML, CSS, and JavaScript with static site generators like Jekyll.
  • Separation of content into Markdown files for different sections.
  • Use of partials for common sections across pages.
  • Embedding CSV data directly into web pages.
• Interactive Documentation
  • Adding interactivity to documentation with HTML, CSS, and JavaScript.
  • Interactive BOM plugin for KiCad.
  • JavaScript frameworks like Vue JS for dynamic tables and sorting.
  • Money JS for dynamic currency conversion.
• Changes in Documentation Practices
  • Startups and small teams within large organizations adopting new formats.
  • Markdown, CSV, YAML, JSON, and software tools make documentation more approachable.
• Actionable Steps for Better Documentation
  • Article by Boldport, Saar Drimer on “Better datasheets” highlights:
    1. Ditch PDFs for browser-based viewing.
    2. Provide machine-readable information and formulas.
    3. Create multiple views for documentation.
• Future of Documentation Tools
  • Speculation on interactive datasheets, searchable BOMs, and Git-backed Engineering Change Orders.
  • Encouragement to share and use tools that enhance documentation.