Software tools for creating awesome engineering documentation
Channel: Sayanee Basu
Date: 2020-09-14

#tools #engineering #documentation
Open standard formats such as Markdown for text or JSON, CSV can be used for creating documentation. Many other types of engineering figures such as graphs, signals, sequence diagrams, and flow charts can also be described in the Markdown text format. For tracking these documents, Git can be used along with static pages that will generate web pages based on HTML, CSS, and JavaScript. Engineering documents such as the bill of materials, engineering change orders, or datasheets can use these technologies to make documents much more accessible, fun, and collaborative!

⏰ TIMESTAMPS
0:00 Intro
00:43 Adding data with Markdown, CSV, JSON
01:43 Markdown syntax basics
02:19 Flowcharts with Mermaid JS
02:52 Equations with MathJAX
03:16 Graphs with Vega-lite and D3JS
03:47 Sequence diagrams with JS sequence diagrams
04:24 Timing diagram with Wavedrom
04:55 Generating TOC
05:17 Exporting Markdown to HTML
05:52 Tracking documentation with Git
06:14 Git, GitHub pages, and Jekyll
09:58 View documentation
10:23 Interactive HTML BOM
10:55 Vue.js for JavaScript interactivity
11:29 Outro: Thoughts on the future of datasheets and ECO

‣ Some links below are affiliate. I receive a small commission at no extra cost to you.

🎩 DEMO FILES 
GitHub pages backed engineering project documentation https://hutscape.com/pine/
Searchable and sortable BOM https://hutscape.com/pine/bom#bill-of-materials
Interactive Bill of Materials embedded in documentation https://hutscape.com/pine/bom#interactive-bom

📺 WATCH NEXT
How I restarted unfinished hardware projects https://youtu.be/OZSr5hX2sBQ
Common datasheet sections to look at when getting started https://youtu.be/lWklOGapYzQ

🔗 LINKS SHOWN
GitHub Markdown Syntax https://guides.github.com/features/mastering-markdown/
VS Code extension Markdown Preview Enhanced https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced
JS Sequence diagrams https://bramp.github.io/js-sequence-diagrams/
TCP 3-way handshake sequence diagram https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Connection_termination
Mermaid JS https://github.com/mermaid-js/mermaid
Si7021 Temperature sensor timing diagram from datasheet page 6 https://www.silabs.com/documents/public/data-sheets/Si7021-A20.pdf 
Wavedrom https://wavedrom.com/editor.html
Wavedrom tutorial https://wavedrom.com/tutorial.html
Vega https://vega.github.io/vega/examples/
GitHub rendering CSV https://docs.github.com/en/github/managing-files-in-a-repository/rendering-csv-and-tsv-data
GitHub Pages https://docs.github.com/en/github/working-with-github-pages/setting-up-a-github-pages-site-with-jekyll
Jekyll https://jekyllrb.com/ 
StaticGen https://www.staticgen.com/
Interactive HTML BOM https://github.com/openscopeproject/InteractiveHtmlBom
Vue.js https://vuejs.org/
Money JS http://openexchangerates.github.io/money.js/
Boldport on Better datasheet https://boldport.com/blog/2019/3/8/on-better-datasheets

🔌 TOOLS USED
https://hutscape.com/tools

🎥 Stock videos used
Video by Pressmaster from Pexels: Group Of People In A Business Meeting https://www.pexels.com/video/group-of-people-in-a-business-meeting-3209301/
Video by Matthias Groeneveld from Pexels: Piles And Layers Of Book For Reading Placed In A Book Shelves https://www.pexels.com/video/piles-and-layers-of-book-for-reading-placed-in-a-book-shelves-3009667/

🎶 MUSIC AND SOUND EFFECTS
Nebular Focus by Dan Henig from YouTube Audio Library
New Morning by TrackTribe from YouTube Audio Library