Software tools for creating awesome engineering documentation
HTML-код
- Опубликовано: 7 авг 2024
- #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 hutscape.com/pine/
Searchable and sortable BOM hutscape.com/pine/bom#bill-of...
Interactive Bill of Materials embedded in documentation hutscape.com/pine/bom#interac...
📺 WATCH NEXT
How I restarted unfinished hardware projects • How I restarted unfini...
Common datasheet sections to look at when getting started • Common datasheet secti...
🔗 LINKS SHOWN
GitHub Markdown Syntax guides.github.com/features/ma...
VS Code extension Markdown Preview Enhanced marketplace.visualstudio.com/...
JS Sequence diagrams bramp.github.io/js-sequence-d...
TCP 3-way handshake sequence diagram en.wikipedia.org/wiki/Transmi...
Mermaid JS github.com/mermaid-js/mermaid
Si7021 Temperature sensor timing diagram from datasheet page 6 www.silabs.com/documents/publ...
Wavedrom wavedrom.com/editor.html
Wavedrom tutorial wavedrom.com/tutorial.html
Vega vega.github.io/vega/examples/
GitHub rendering CSV docs.github.com/en/github/man...
GitHub Pages docs.github.com/en/github/wor...
Jekyll jekyllrb.com/
StaticGen www.staticgen.com/
Interactive HTML BOM github.com/openscopeproject/I...
Vue.js vuejs.org/
Money JS openexchangerates.github.io/mo...
Boldport on Better datasheet boldport.com/blog/2019/3/8/on...
🎥 Stock videos used
Video by Pressmaster from Pexels: Group Of People In A Business Meeting www.pexels.com/video/group-of...
Video by Matthias Groeneveld from Pexels: Piles And Layers Of Book For Reading Placed In A Book Shelves www.pexels.com/video/piles-an...
🔌 HARDWARE LAB EQUIPMENT
EEVBlog Digital Multimeter 121GW www.eevblog.com/product/121gw/
Saleae Logic Analyzer amzn.to/3n47Jxh
ATTEN-862D Hot Air Gun workstation s.click.aliexpress.com/e/_A7zoa8
💻 SOFTWARE USED
dotfiles for terminal configuration github.com/sayanee/dotfiles
KiCad kicad.org/
CoolTerm for serial monitor freeware.the-meiers.org/
PartsBox for inventory management partsbox.com/
GoodNotes for highlighting datasheets www.goodnotes.com/
🎶 MUSIC AND SOUND EFFECTS
Nebular Focus by Dan Henig from RUclips Audio Library
New Morning by TrackTribe from RUclips Audio Library
📹 VIDEO PRODUCTION GEAR
iPhone for recording video
Microphone Audio Technica ATR2100-USB for voice recording amzn.to/3gsOiwA
IKEA TERTIAL Work lamp stand hacked as a microphone stand amzn.to/2QJWnCx
Tripod SLIK SDV-10iPhone holder Xiletu XJ-8 s.click.aliexpress.com/e/_AVrL8v
🎬 VIDEO EDITING SOFTWARE TOOLS
DaVinci Resolve for video editing
QuickTime for recording screencasts
Canva.com Наука
FYI - Markdown is simply a specific implementation of the category of languages we call Markup. For sure markup languages are the future way of documenting especially technical engineering projects, small and large.
This is one of the best tech videos I've seen. Good balance of telling me about a couple things I hadn't seen before, and showing how to use. The completeness of your references and toc in the description was so useful.
Absolutely wonderful !! Thank you so much Sayanee for this extremely useful & informative walkthrough of markdown.
Thank you for another great video, Sayanee.
I didn't know about Wavedrom, it's amazing :D
awesome, wish I had saw your clip year ago, so productive!
Thanks a ton for sharing these tools. It’s been a struggle to draw flow charts with drag and drop tools.
Thank you for this! I recently started a new technical writing job with a team that needs their code documented and these are great tips.
Your videos are always very useful. Great content !
Thanks for this video. I’m mechanical Engineer and this give me a lot of ideas 💡 how i can make nice documentations
Amazing tools to create technical docs! Thanks a lot for sharing, new subscriber :D
It feels like you unloaded your brain into a video. Very interesting and amazingly useful tips, thank you for sharing your knowledge.
Great video 💚 It has given me so many ideas to implement in my ongoing projects
This is awesome, I'm now subscribed!
I was in need of something like this without even knowing it :D Very helpful tutorial
Great info. Thank you!
thanks you for the info. I have been slopy with my documentations over the years. I will get back on track with your advice.
Nicely presented. Lucid and to the point. Thanks for sharing.
This is very helpful. Thank you for the details.
Beautifully explained!!⭐❤
Great video, thanks 👍
Wow, very helpful.... Great video thank you :)
Very good. Thanks.
Good work 👍❤
Great methodology 👍💖
Excellent video
Thank you
Thank you so much
Just awesome
Beautiful and well explained demos
Will use in my Network security blogs and diagrams
Great info,thanks, Many organisations still use microsoft word as primary documentation software, (ultimately it is duplicated in fancy Adobe suite but mostly it starts with ms word) which is probably worst choice. Text based document is way to go forward.
OMG interactive html bom is soo cool
Thanks Madam.
From south India.
This is a great video. Also it is not surprising that Hardware folks are never aware of JS frameworks. I have worked both on web application and embedded application. Never thought of making use of these js libraries for use. Thanks!!
Yes, you have identified the skill or awareness gap between the hardware and web developers correctly :)
As I learn how to use these skills from both areas in IoT technologies, I hope to share them in such videos as well.
@@sayanee Looking forward. I am also watching the videos that I have missed from the channel.
omg, this is so good. I have been looking for something to draw a timing diagram for years. Do you have anything to draw geometric diagrams especially representing angles?
If it's anything more complicated like geometric diagrams, I'm guessing you will have to use hand-code SVG. Maybe try d3js d3js.org/
👍🏼 learnt a lot in such a short time… #writethedocs
What is the colour scheme that you're using in iTerm2?
Oh no! I keep changing it 😅 I believe this one was either Atom or Material dark theme. Even within Atom / Material, they have variants.
Hey, thank you for the great video, can you please tell us the name of the book and author Documentation on your desk please.
Thanks!
It's actually the August 2018 edition of Increment increment.com/about, a print and digital magazine by Stripe stripe.com: increment.com/documentation/
This is great thank you!
2:20 Cool tool, but the generator on github pages doesn't support it. Fortunately, you can include a third-party template. You do not need to copy the template to your repository. 👍
Yeah, all the Markdown-based documentation won't be supported when you view them on GitHub or any other Markdown reader. I prefer to simply render them as a webpage / HTML and send the URL to the readers. Either way, as you mentioned there are many other options 🙏🏼
Could you give an example of a third-party template? I didn't understand that part about copying the template to my repository 😅
@@sayanee Yes please. Here is an example of loading a third-party template, while graphs are drawn directly on the site.
github.com/kc-doam/manual/
As it turned out, in the settings not needed.
*plugins:*
*- jekyll-remote-theme*
Bengali?
Yes, I am :)
dekhei bujhechi..amio didi.. nice to meet you..
@@sandhyaash7134 Amaro khub bhalo laglo!