BROADCASTS.com

b'

Christopher (@stoneymonster) and Elecia (@logicalelegance) discuss embedded systems education and project documentation.

Elecia wrote about her love of notebooks on the https://www.embedded.fm/blog-index.

yEd, for when you don\\u2019t have Visio. Asciiflow.com, for when you don\\u2019t have yEd (or you want to put diagrams in your comments)

We talked about many different documents and tried to note design vs implementation, product vs engineering vs user, and why we wanted them. We didn\\u2019t mention mechanical things because, ya know, software engineers. Some documentation we mentioned:

• Product documentation

• Schematics with block diagrams and comments. Also a GPIO to function spreadsheet.

• UI flow when the system has a screens (Balsamiq for wireframe testing UIs)

• SW spec and design doc: what do we plan to build and what are the tricky parts

• SW configuration and SW developer docs: how to rebuild the computer that can build the code from scratch, also notes on debugging methodology

• User manual: Usually not written by SW but may need SW\\u2019s patient input

• Code comments: Functions and files get 5Ws: who, what, why, when, where, and how.

  • Who should call this?

  • What will its effect be? (\\u201cWhat will it do\\u201d but not in line by line detail!)

  • How does it work?

  • Why does it work this way?

  • When should it be called?

  • Where are its parameters? (\\u201cWhat\\u201d works here too but \\u201cwhere\\u201d is nice to remind you to check your memory assumptions.)

• Repository checkin comments

• Style guide (Such as Google\\u2019s or PEP)

• Manufacturing docs and tests docs

\\xa0

Adafruit and Sparkfun both write good documentation, writing to users about how to use their code. Elecia likes Adafruit\\u2019s sensor library as a good set of code to review (including how much is in their docs vs their code).