Embedded10 Mai 2019

288: You Got a Screen!

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't have Visio. Asciiflow.com, for when you don't 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't 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's 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? ("What will it do" 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? ("What" works here too but "where" is nice to remind you to check your memory assumptions.)
Repository checkin comments
Style guide (Such as Google's or PEP)
Manufacturing docs and tests docs

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

Denne episoden er hentet fra en åpen RSS-feed og er ikke publisert av Podme. Den kan derfor inneholde annonser.

Episoder(580)

533: The Garage Is Open

Author Susan Lammers joins the show to discuss the 40th anniversary edition of her classic book, Programmers at Work. We discuss what it was like to interview young and pioneering software developers ...

4 Sep 59min

532: It's Still Real Fire

Kevin Santo Cappuccio, founder of Architeuthis Flux, joins the show to discuss creating Jumperless, an open-source breadboard that replaces physical jumper wires with software-controlled analog crossb...

20 Aug 1h 9min

531: Sequestering the Mess

Elecia and Christopher celebrate winning the IEEE Educational Activities Board Meritorious Achievement Award in Outreach and Informal Education! A huge thank you to Mark Omo and the wonderful listener...

6 Aug 1h 7min

530: A Living Highlighter

Marine biologist Dr. Steven Haddock joins the show to share the alien, glowing, and transparent wonders of the deep ocean. We discuss his beautiful new book, The Radiant Sea, and explore the complex e...

25 Jul 1h 8min

529: The Narwhal Looked Amazing

Chris Svec returns to the show to discuss the messy, non-linear realities of engineering management and onboarding new college graduates. We explore why companies should bother hiring fresh grads in t...

9 Jul 1h 22min

528: Goldfish Chunks

Tyler Hoffman returns to the show to discuss diagnostics and observability data in embedded systems. We catch up on his life after startup acquisition, explore the hows and whys of keeping product dat...

25 Jun 1h 10min

527: At The Jellyfish Conference

Chris and Elecia talk about pushing out of their comfort zone, networking advice, adding STARs and action verbs to resumes, using rust, thermo forming plastics, soldering together audio gear, and winn...

12 Jun 1h 9min

526: Take A Taste Of Engineers

Dr. Victoria Serrano spoke with us about STEM outreach, fostering curiosity, and inspiring students with engineering education. Victoria is a professor at the Technological University of Panama (her ...

28 Mai 1h 1min