Embedded - 288: You Got a Screen!

Episode Date: May 10, 2019

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).

Welcome to Embedded. I am Elysia White, here with Christopher White, and today it's just going to be us. Hey, everybody. Do you remember episode 24? I barely remember episode 285. It was only two ago. In episode 24, listener Jim GF posed an interesting question about how to tell if you are a good embedded software engineer. I am not, because I develop in Swift for a phone.

At the time, we took his email, which was perfectly reasonable, and then used the whole show to answer a different question. Isn't that how we do everything? Well, that's what I was planning on doing today. Even with our guest. We invited you to talk about this, but little did you know. Let's talk about whales. So today, our email is from Mike, who says, I'm a high school technology teacher in New Jersey, and just finished listening to all your episodes after being asked to create a two-week embedded system summer program last year. All right, first, I hope you didn't listen to it in two weeks, because that's a lot of episodes.

So going on, Mike says, we settled on the STM32 nucleo boards and the Kyle MDK after attempting to get high schoolers to solder QFP64 chips. Yeah, I couldn't solder that. I can barely solder, you know, 8-pin dips. Mike says some nice things about us that I'm not going to repeat. And then he had a couple of questions. You mentioned across a few episodes how there's a disconnect between engineering education and real-world education.

I strive to make all of my programs as relatable to life as possible. Can you please elaborate on these comments and maybe talk about what you would consider an ideal educational experience? Okay. I don't know. Do you know? Well, I mean, let's, I think we should state what we think is missing in the engineering curriculum. I mean, but we're basing this on old knowledge too. So I'm a little hesitant to go and say it's all broken. It's been broken for 30 years.

Yeah, our college experience is slightly out of date at this point definitely our high school experiences but i think it's probably true that most people who want to write software for computers go one of two paths right they go computer science which doesn't really focus on any particular aspect really necessarily of industry computing. Like it's not necessarily all about web stuff, but it's also definitely not about embedded stuff and devices. It tends to be, our CS curriculum was somewhat theoretical for maybe 30% of it. And there was a lot of languages we learned for various classes that weren't generally applicable to anything once you left academia. But then there was some stuff that did apply.

Like there were several classes in C++, which even though the problems that we were solving were like, here's a breadth-first search algorithm. This is your homework assignment. Find your way through a maze using these various methods or some database stuff. Even though you were solving those kind of problems, you're still learning the language and how computers worked and how to talk to them. And C++ being what it is, is something that you can immediately apply to working on devices and robots and things like that.

But it was sort of a mismatch. I don't remember in my schoolwork ever doing anything with a device. It was always programming for a Unix system and writing command line or other executables, and those were my assignments. Definitely. We didn't have a robotics curriculum at all. Yeah. And we mostly wrote code for big systems. with PowerPCs or MIPS, and we coded them in C in a custom operating system the company made, and they were very much embedded systems.

But I didn't think about it that way. I was like, oh, okay, I'm just writing more software for another box that looks vaguely like a pizza box. It says Cisco on it instead of Sun. But it was true. We were downloading firmware, cross-compiling, and all that stuff, and it just never occurred to me that that was anything unusual. you know it was true that we were downloading firmware cross compiling and all that stuff and it just never occurred to me that that was anything unusual and we learned to develop

but we didn't necessarily learn how to develop with other people i mean sure we had team projects i mean they had that whole class right i learned i learned all about teams for a couple semesters. All about teams and how they don't work. I already knew that, but it was reinforced when, you know, a couple people did all the work. But teams in business actually worked a lot better than the teams in school because we had a manager when we got to our jobs and the manager, at least for a while, told us what to do. I think the consequences of being a layabout are slightly higher in real world. We're going to stop giving you all your money. Yeah.

And I'm going to kick you out, and you're not going to find your next job. Versus, yeah, I might get a C in this course, which is fine. I have better things to do. Yeah, right. Then there was, we had version control in one class. Let me remind you what version control was when we were taking these classes. That class was CVS. CVS was the good one.

Yes. RCS is what you used for most of your stuff if you were, yeah, there wasn't. But when I got to industry, that was like way important yeah i didn't know that that was as important yeah it wasn't something i was taught in school there wasn't a lot of practical stuff yeah i mean we i think for the the project we were talking about with the team i think we used rcs yeah we did a terrible job at it there were no branches or anything. It was all, I don't even remember how we shared code. It was probably some sort of nightmare. And then we didn't, we started code from scratch almost every time. How often in your professional

career have you gotten to start code from scratch? But that was a, that was a product of our, of the time, right? You don't, you think think now they oh oh i see what you're saying i thought you were referring to like assignments and stuff where you might pull in lots of sorts of easy frameworks now to do the sorts of things that are just boilerplate that you had to do for every uh everything you build but yeah uh no i i don't it's probably rare that anybody gets to build much from scratch coming into any company. But I did a couple, you know, startups. Yeah. No, when you get to startups, definitely.

But it seemed like a lot of it was fixing bugs. And I don't feel like I learned to read code in school. No. It took me a long time to understand you should read code. I have no idea why I got hired. My first code was so bad. I sometimes think back on that and go, wow, why did they even let that into the code base?

Just long, you know, if then, if then. Huge functions with just, you know, we'll just go through every possibility with an if statement. Yeah. I mean, you learn so much in your first few years at a job. So. I mean, you learn so much in your first few years at a job.

Yeah. So that's why, you know, I don't want to be too hard on academics because how could they teach everything? How could they better prepare people? And there are ways they can better prepare, but I don't think they can adequately really prepare. Unless a student picks a very narrow focus

and says, I'm going to work on robots focus I'm going to work on robots I'm going to work on consumer products with networking things I'm going to work on these kind of devices with these kind of processors there's no way for a school to have a breadth of teaching subjects to be able to cover all of that,

even if somebody were to choose a particular narrow focus. And I don't think they should. You only have so many hours in a day. Yeah. While algorithms was not my favorite class and not the most useful class, it was a necessary class. And the C++ class you were talking about,

I don't know, it was like CS60 or... Yeah. It was supposed to be about algorithms and computers and all that. Oh, yeah, and it wasn't all about C++. I think there was some other... ML. No, it was Rex. Rex.

Remember Rex? I didn't do ML. Anyway, in order to learn C++, you have to use it on something. And to try to learn C++ by reading code that's out there, given the wide variety of styles and idioms, I don't think that's how you'd learn it. So you have to kind of learn it yourself and then learn how to learn all that stuff. And then you finally get into industry and you're like, oh, I'm not doing anything I was doing at school, but I have the tools to learn how to do this. So to bring it back around to the question.

Was there a question? Yeah. I think there's a lot to be said for just that initial kind of bathtub curve, not bathtub curve, that's the failure thing. What's the learning curve? The first part of that learning curve where you feel like, you know, for a couple of weeks you're on top of the world and things are coming together and before you find out that, you know, the hard parts that are lurking around the corner.

I think it would be helpful for schools to expose kids, sorry, kids, students. Well, he said high schools, high school teacher. um,

to be kind of exposed to a little bit of everything just to, just to see, uh, and maybe, and maybe that will inspire them to go dig a little deeper while they're still in school. So like if they could have a course where as part of it, it's like, well,

yeah, like he says, here's a STNucleo board. We're going to show you what these tools look like. We're going to do some sample projects. At least then it's not like, oh, I've never seen any of this before. This is weird. You know, you can get a concept of what is cross-compilation. What does it look like to attach a debugger to a device and use GDP or whatever's in your IDE across a JLink or an STLink? What is JTAG? You know, some of these words that people might throw around. I remember, you know, being in first job and people just throw words around.

I'm like, yeah, sure, okay, uh-huh, yeah. Oh, I know all about that, certainly. You know, I'd go home and furiously... Yahoo itoo it i guess or altavista it or yeah it wasn't ask jeeves it wasn't that time yet no it definitely wasn't google either google didn't exist for quite a while um so yeah but things like jtag i mean people would talk about that and i would kind of absorb things it took me forever to figure out the ICE and JTAG. Yes. They meant the same thing to different people?

Well, in one company, people talked about JTAG, but they were talking about JTAG like the real way to use it. You know, to look, okay, we have 50 chips, and we'd like to query every chip's, you know, pin state during manufacturing. I'm like, okay, that's what that is. And then people would talk about it for debugging. I'm like, what are you talking about? That's not JTAG. Well, and the double e's have it worse because they learn all of this theory and analog and antennas and so yeah that

was and then they have to buy parts that was the the second path to developing embedded besides cs is you go in for a double e degree and you find out you like it they're a little they have some of an advantage because they'll see devices, right? They'll see microcontrollers and microprocessors and things outside of the pizza box environment. Well, sure, you take a microprocessors course, you learn to build a microprocessor.

That doesn't help you read a data sheet. Yeah, I don't know what's in the double E curriculum these days. I have to believe there are classes that are you know microcontroller based well i think that's why chris gamwell has his contextual electronics because how do you you don't learn schematic capture in most schools or if you do it's like a tiny subset and you don't really learn, maybe you learn spice simulation because that's a useful tool for analog development. There's so much you don't learn about actually

putting your hands on something and making it manufacturable. And so, yeah, there's, but again, you only have so many hours in the day. How do you teach everything? And what most schools, most high schools, what most colleges do is they try to teach you enough that you can learn and enough that you have exposure so that as you go forward, you can figure out what you want to do. It depends on the school too, because a lot of schools aren't prepping for industry necessarily. It's, you know, this is a CS department. We expect you to get out of here and get a job or go continue in grad school and do research and stuff.

It's kind of like the math department. There's applied math and theoretical math and they're very different. But I'm hesitant to say academics, academia should become a training ground for industry in any real sense. You should learn how to learn. You should get exposed to a few things. And you should form kind of the solid base level knowledge you need to succeed. But then companies should be expecting to hire people who need to ramp up on working with real things.

We get really lucky with HP and Cisco. They were big. They had the new college graduate programs where they kind of just knew how to onboard us into usefulness. Yeah. So I don't know that we've answered his question yet. Let's go on. Do you want to continue?

Do you want to try to wrap it all up with a bow? Go ahead. No, you do it. No, no. I don't remember the question. That's why I'm stalling. What was the question? What are the gaps?

Maybe talk about what we consider an ideal educational experience would be. An ideal educational experience. Oh, okay. I think a Montessori preschool is mine. Yeah. Just give me all the tools and toys and I'll learn whatever I want. I think, like I said, I don't want something to be so narrow that people come out as expert embedded engineers of college. Because I think that's totally inappropriate.

If you want to do that, then there should be different kinds of schools for that. I think you should come out with a broad base of knowledge if you're in the computing field about all kinds of computing and all kinds of software and be able, be prepared to go into almost anything at the very base entry level. And of course there's going to be people who are super gung-ho and they do projects on the side, they do the robotics club, and they've decided during the course of their education where they want to go, and that's great.

But that shouldn't be up to the school to say, you need to pick this. It should be, here are some options for you to go deeper if you want. But the school's job isn't, okay, here's somebody on day one who's ready to make contributions to a code base at Twitter or Apple or Google or wherever. I don't think that's appropriate. No. It's more about

learning to learn, learning to persevere, learning to communicate with other people. It's weird. They say, you know, you're getting an engineering degree. What you're getting is not that. college education and why many people who don't have it wonder what in the world am i missing i have all the technical schools technical skills they do why can't why do companies need that and it's because there's this expectation of breadth over depth i guess so i guess so yeah well i mean i think part well no i think part of it is it is it's an easy crutch for schools to say, okay, well, we have a college graduate, therefore we don't have to think too hard about, you know, digging into this candidate's skills. Even though the skills evaluation would be the same during an interview process, whether you're talking to a college graduate or not. I think there's some assumptions made with a college degree. Yeah, yeah. And whether they're good assumptions or not is I think there's some assumptions made with a college degree. And whether they're good

assumptions or not is pretty irrelevant. It just might be assumptions that are hard to verify. Yeah. Or they are perceived to be hard to verify. But, you know, if somebody has a history of working successfully, I think the college degree starts to matter less and less. Over the career, yeah. Okay, now we're going to go on. Documentation is very often emphasized in education and competitions. There have been a few times when talking about getting government approval and taxes that Mike recalls us mentioning documentation. Taxes? I don't know. Is it really true that today's engineers must document everything slash keep personal engineering notebooks? So, I have a very short answer to this question.

No. No, you will find in many companies that there is no documentation. Or there's a wiki page that somebody wrote four years ago, which briefly touches on something slightly tangential to the thing you're interested in, but has since been completely outdated and unkempt, and nobody's looked at it in the intervening four years. Also, the code you're looking at may have zero comments. None. Zero.

Okay, I lied. It may have a copyright at the top because the lawyers require that, but no other further documentation about the code, because, of course, all code is self-documenting. Should I go on about how there is no expectation of documentation at most places? I had some code comments recently that were an error put out by the compiler, a Stack Overflow web page link, and a line of code. And so I, you know, why? And so I had to go to the Stack Overflow page and figure out that this line of code was to prevent this other error, which was inscrutable. And it infuriated me.

I was like, this is not how you write code comments. This is awful. And it was like 30 lines of comments that should have just been, I had an error, I went to Stack Overflow, here's the page, this fixes it, I don't know why. Yeah. No, I've seen a lot of very, very broad array of documentation styles and requirements in my career.

I use a bound notebook. I have never had a supervisor signature. I have dated pages and have crossed out white space, but I do this because i like it i did all that when i was working at medical places we had good documentation in the medical places because if you don't then you're no longer in operation so it's one advantage of being in a regulated industry is you can't get away without documenting but that doesn't mean your code is well documented necessarily it just means you're following the forms of all right we have a requirements document and, you know, testing documents and a software spec, but those aren't the kind of documents that you could reverse and say, gosh, this guy made this decision two years ago and we really don't understand the code. We don't understand the thinking behind it or the design. It's just here. That's the sort of stuff that your day-to-day engineering work,

real documentation, continuous documentation really helps because you're not, as we've said many times, you're not just doing it for other people. Sometimes you're doing it for yourself down the line where you can't remember what you were doing. But self-documenting code is a myth, especially as things get more and more expressive and languages change. If you're doing anything that's even slightly interesting,

I mean, any sort of algorithm is hard to understand reading the code. I'm going to go back to notebooks, and I do want to talk about code, but I'm going to go back to notebooks. The and I do want to talk about code, but I want to go back to notebooks. The supervisor signatures, dated discovered something, then even if somebody got a patent on it in 2002, I could legally sue them and say, I was the first to discover this. It's my patent. Now that the US patent system has moved over to first to file, it's not as important to have this dated, multiple people have looked at it to prove that it happened when I say it did, sort of notebook. Those notebooks are kind of out of style. I use my notebook for that when I first started and was doing patentee stuff. I did do all of that, but having gotten into the habit, now I use it for my own purposes.

I use it more as a lab notebook to keep track of what I've done and what hasn't worked and what I still have to do. It's my diary. I admit it, it's my diary. Okay, going on with what Mike was saying before we get back to code comments. Getting students to document effectively has always been a struggle. Either they don't do enough because they think it's a waste of time or they do too much trying to impress. And so I think Mike's question is what is the right level and how do we figure it out? All right, go.

Getting them to do the right amount. I think you need to show examples. Yeah. I think you need to show examples tied to various projects that you find to be appropriate levels. I don't think if you say, you know, as part of your assignment, document the design of your code and choices you made in implementation, I think you'll get an essay from most kids, don't you think?

Instead of what you're expecting. So I do think examples probably would be good. I think bad examples too. And I think maybe having an editing assignment, right? Like here's some documentation that goes with this code. Edit this to be more concise, more understandable, whatever. Oh, yeah, you'd have this line that has, this sets the index to one right next to i equals one.

Right. Because that is so a comment that's that's code comments but um yeah and i don't know which specifically he's talking about whether it's a design document that goes along with something or the the encode comments um encode comments yeah you get into things like that where people are saying said i equal one and then the next line is like one and it's like that that is self-documenting i got that i can i can do that um so what advice do we have if we want to talk about professional documentation and i have a list of documentation here do you want to start on code comments or do you want to go down my list and you have a list then you are superior to me i have no list i have not

documented my comments about documenting. Yes, exactly. So the first thing I have on my list are product documents. And this is, you know, a lot of engineers don't write this, but if you are writing your open source library, if you are maybe trying to do a competition where you're talking about robotics. You need something for the layperson that says, what is this? And I think, you know, I go back to the five W's, who, what, why, when, where, and how. Don't even argue with me about the how. I see those fingers.

Don't even argue with me. Who, what, why, when, where, and how. What's that six? But only five of them have Ws. I told you don't argue with me. I was just trying to count in my head and it wasn't working. So who would use this? What does it do for them when would they use it who what why where where would they use it um is this is this for

uh unix is this for a mac is this for windows on their iphone where would they use it? Why? Why is this implementation good? And how? You know, okay, you have convinced me that your widget does something I want and that I can run it on my computer. How? How do I start this puppy? How do I install it? How? I think a lot of, I do that with code comments too. It's who, what,

why, when, and where, and how for the code function header and for the file header. And then in the code itself, pretty much it's why. why did I do this thing that doesn't quite look like it's efficient? Why did I do this thing that is weird? It's not what, it's not index equals one. It's why is index being set to one instead of zero? Index is being set to one because we've already done the zero element above. So that's kind of my general rule for a lot of things. Your product documentation doesn't need to be 25 pages long. It needs to answer the basic questions. Not how would I explain this to my classmate who is in my same class, but how would I explain this to a professor who's in a different class?

To somebody knowledgeable-ish, but not knowledgeable about this. Do you agree? Sure. Okay, let's go on to schematics. I would also add that if you're doing documentation outside the code, you should do that with something with version control. Oh, yes. Whether it's from Confluence or your wiki or whatever, but track changes isn't it? Track changes isn't it. If you're using a Word doc,

you can now merge and compare Word docs just fine. Google Docs is fine. It has a history. But as your code grows and changes, your product documentation will as well. So version 2 is going to be different than version 1, and somebody will want to get to both of them. Okay. And, you know, if you're doing a medical device, you have a bunch more of things to do there. But the product document is just for the user, for the investor, for the not engineer. No? Isn't that a requirements document?

It could be a requirements document. But for what Mike is saying, I think that the first product document is just the, what the heck are we building? Okay. And if you want to get more detailed, what the heck are we building and how are we doing it? How are we going through each state?

What is it doing all the time? But there are so many times I go to an open source project, somebody has said, oh, you should look at this. And I look at it and I look at it and I still have no idea what it is supposed to do, whether it will work on my system, how I run it. Is this a Python import sort of thing or is this a compile? I want to know from the outside with no foreknowledge, what is it I am doing here?

That is, you know, yeah, with medical or you're doing software requirements document you're doing product requirements document you're doing hardware requirements document but at some point you just want to know what the heck is this but yeah all of these things are hard without seeing them first and seeing a good an example of a good one and a bad one so that that's that's where i would start if i was a teacher is to try at least to source some of those things and you know just look through github look through github look through some open source spark fun and adafruit both have projects that are geared both for the new developer to use and for the new developer to breed. And they do something that I really like.

They have how to build it. It's not just what does this do, it's how do you use this. And I think of those as more software configuration and software developer documents. You know, how do you debug this? And those documents are not for the outer user. Those are for other engineers. And those are step-by-step. Here is how to set up

your environment. That has saved me so many times. I had a client come back after a year of them being over and they wanted me to debug some little thing. And I'm like, I don't know how to run your system anymore. But previous me had written a little document that said, here's how you build, here's how you attach the debugger, here's a picture, and here are the five things you're most likely to need to debug. And it was so nice. It made me write the same thing for the other two clients I was working on that day. It's surprising that more people don't do that. In medical terms, it's the software configuration document. But it is one of the most useful documents for a project.

It's also the document you give to somebody else who might be helping you. And again, open source projects often miss it, so that when you start working on an open source project, you have a make file, and that's it. Good luck. Have fun, kid. I want something a little nicer that tells me where to go and what to do. At least as a beginner. I haven't seen this before.

All right. Okay, schematics. I tweeted a while ago. I'm very good at this. That these were the best schematics I had ever had the privilege to read. And people wanted to see it, and I couldn't because it's a client. But they did set the bar higher for schematics than I have ever seen. And the thing with schematics,

the electrical engineer spends a lot of time reading data sheets and figuring out what parts they need and how they're going to work together. They do some math related to low-pass filtering or to resistor networks or to how the ADC counts go to voltage. And then they hand me a schematic that has net names and part numbers. And I have to redo all that work. I may have to redo all that work anyway, but at least tell me what you were thinking. So this schematic had a block diagram on the front, always nice so that I generally know what you're building. It had for each page, it had a short description, two sentences about what was on the page.

And then for each section on the page, it did the math. It showed me what math he'd used. And it showed me what he expected. And it could be used by a board bring-up person to figure out where the voltages should be. And it could be used by me to make sure that I was doing the voltages right. And that I, my board was still good after I'd plugged it in wrong. It was beautiful.

No comments, huh? I haven't done anything with schematics in probably 12 years. Really? Has it been that long? I mean, I've done a little bit at Fitbit, but not nothing more than, you know, are some of these pins connected?

But you've had to do stuff with data sheets. Yeah. But those are mostly application stuff, like what does the firmware developer have to do? Where are the registers? I was really happy with these schematics. Not only were the net names named nicely not only could i search it in pdf why is that ever not an option uh it was the electrical engineer had put down his thinking and put it down in a way that i could use i like it when the pages make sense yeah I mean he had a power page

he had a processor page he had a connections page it was very nice but I think that's part of the block diagram because once you have a block diagram you've kind of separated stuff and it makes sense I don't know sometimes I remember something recently that were like

okay here's a part on the whole whole page is one part the connections go off to other pages that we're like, okay, here's a part on the whole. The whole page is one part. Yeah. The connections go off to other pages. It's impossible to decipher. It's a long list. Yeah.

And papers, for these days, schematics tend to be a lot of chips and not much else, right? The passives are there, but we're not really looking at those so much so it's you know a page with a 50 pin chip or probably something with a better number of pins but you know the next page has another chip and they're connected you know through 8 or 16 lines and it's just hard to navigate it's not really you know the pdfs are not really the way to look at those it'd be better if we had some other method of for the kinds of things we do better that we had some some other medium for reviewing it i think than pdfs with pages and

and even when i i hope when i give in and install Altium Viewer or whatever viewer I need, it isn't better. I mean, sometimes I can click and I can find where the net goes, but there should be some nice rule about whether or not you put it on a different page or whether you connect it, whether the wire connection is shown. I don't know what the rule is. Electrical engineers, you can tell me. connect it, whether the wire connection is shown. I don't know what the rule is. Electrical engineers, you can tell me. Okay, so schematics, it's always lovely when my electrical engineer also gives me a pin spreadsheet that says which digital pins I have and what they're supposed to go to. Because again, why am I figuring this all out again? Why didn't you just give it to me?

That's the kind of thing I'm talking about as the schematic being the wrong medium for it. It's like, here's the schematic, figure out your software, configure your microcontroller. It's like, you didn't even use consistent names for all of the nets and things. Yeah. Just give me a damn spreadsheet.

And it really is about, you had to figure all this stuff out. You had to figure out which pins could be spy. Why are you making me go from the chip pin number to the internal pin number to the net name? You had to figure all this out. Why are you torturing me? Quit torturing me, electronics engineers. Okay. So going on from schematics.

Software specs. We talked a little bit about software requirements spec. But if you're not doing medical, you just want a decent set of documentation, then you might want a software spec. If you're doing things with other people, especially if you have an interface for other people, if I'm doing half the code in a code base, I want to have a nice spec so that the person and I who are working on it don't end up at the end having done the same half and now having to scramble for the other half.

Do you have any advice for software specs? I mean, doing what the medical requirements are is the easy way to go. And in that, you take... It's hard to sit down on a blank sheet, right, and write a spec for software. What is it, right? Is it the spec for all the product software? Is it a spec for a particular module? Is it a spec for a subsystem of a particular module?

So it's hard to talk in these terms about writing a software spec without being specific. The nice thing about medical is that, you know, there's a requirements document and the crutch is, okay, I write a software spec for my product and it says how the software implements each of the requirements. That's the easiest thing to go off because then you've got some idea of what you're supposed to be writing about. It's how the software fulfills the requirements of the product. And that can be various levels of detail. It can be two or three sentences per requirement, like, okay, the software will have a user interface.

The requirement is the user can configure the product, and software spec says the software will present a user interface with various fields for configuring a product. And then you can break it down into more and more detail as you write more specs for smaller and smaller pieces of the software. But if you're just coming at it from nowhere and like, okay, I'm going to write a spec for my application. I know what the application kind of does, but then you end up with those prosaic essays about your software that have no structure. I think a software spec should start with a block diagram, which will look a lot like the hardware block diagram, but also have some notes on algorithms and drivers. And it should also have some description of the input and the output of the system.

And then I think it should have a flowchart. I mean, it doesn't have to be a flowchart flowchart, but let's face it, embedded systems have some sort of state machine-y flowchart thing. So let's document that. And the thing about the software spec, the software requirements document, the software design document, I'm kind of mashing those two medical documents into one. But the thing about doing the spec is that you try to do it first because this is a good time to do the design. And then you implement it and now it's out of date because your implementation plan is not the design. And then you implement it and now it's out of date because your implementation plan is not the implementation. Your design is not what's going to happen, but you do the design because it is a very good exercise to think about what's going to happen. And it will decrease your implementation time significantly because you'll have thought ahead just a little

bit. I'm not talking about spending three weeks on documentation. I'm talking about spending 20 minutes a day. You know, what is your design for today? And maybe at the beginning of a project, it's four hours. So you have a better overview, But it doesn't have to be you write a bunch of documentation and then you're done. I think you're underestimating how hard writing is for most people. I think those numbers are pretty damn low. And yet, how many times have you been shocked that 20 minutes of thinking about it actually... I'm more often shocked that three weeks of thinking about it doesn't get me a finished document that I like. Oh, yeah, that's true.

It's kind of like podcasting and always hating your own voice. You will always hate your document. And it will never feel done. So that is a problem. But if you have a state machine and you have a block diagram and you have a few words about whatever cleverness you're going to put in, that's a decent start. You don't need to go overboard. What you want is to explain to the people who are working with you, with your instructor, with your classmates, with your professional colleagues, what you're doing. You don't need to describe it to someone with a

non-technical background or you don't need to describe it to the CEO of your company. It's a document that is for engineers engineers and so you can leave out a fair amount of detail and given writing you can it's okay not to have all the grammar in place i think i think keeping it yeah if you put in too much implementation detail you're right you end up with out of date documentation because that's always going to change a lot. So I think it's good to start keeping it high-level and keep detailed stuff if you want to document it in separate documents so you don't kind of pollute the higher-level documents with changes that if you make them and it's high enough level,

you don't have to adjust it. I also think that a lot of people, I don't know, I've seen a lot of documentation that's just straight up prose when it should be 75 of documentation that I've needed to read for stuff. And it's like, this is describing a doc. This is describing a diagram. This is eight, eight paragraphs of this connects this and does this when, you know, a picture would be much, much, much easier to parse very quickly.

And if you don't pay for Visio, there's yed which is okay there's ascii flow there's ascii flow there's you want everything in text like some sort of weirdo like i am there's writing it on a whiteboard and taking a picture it's better than nothing it's better than eight paragraphs of prose um and i i mean i do it in pencil and then I ink it and then I take a picture and then if I need to change it that is when I go back and I do it in usually Yed for me because being able to lay it out

in a way I'm happy with takes a while and so pencil is the way to go at least until i'm willing to commit to it being okay uh screens i i recently started a project where we have uh an adafruit like 3.2 inch tft uh so it's a it's a screen it's a little screen it's a little screen. It's bigger than a watch. You seem shocked by the existence of screens. I am. You know, after, after working on. Right now, without shifting my eyes, I can, I can see at least five screens.

But some of them are, are, you know, boring screens. And this one has actual, you know, colors and pixels and everything. Welcome to 19... Oh, is it... Are you still on... Have you gone into the 80s? I'd say welcome to 1991. Anyway.

TFT color screen. Yeah. Okay. You got a screen. I was trying to explain some UI design and then I was like, you know what? I don't want to. They need to find somebody who can do UI design and they will. And for the first version, I don't want to implement it 12 times because they're new at having a screen too. And with Christopher's help, I came across Balsamiq, which is this online tool that you put in your screen size and then you can design your screen and your flow and you can have buttons and when you run it, you can push the buttons and it all

acts like your screen is going to act. And I think the thing that I expressed to them that I'm happy with was, I'm okay with implementing the screen twice. I know we're going to have to, because whatever we do the first time, we're not going to like. But I don't want to implement it four or five times, which when you're doing UI design, can you move it over three pixels? What about up? Can you make it fade in? Can you make it swoop in from the side?

That's just a lot of wasted work. So why don't you go off and play with it yourself and get back to me when you're ready. Do you do screen designs or does that all come from product? It all comes from product. Yeah. But the thing about Balsamiq that you're kind of alluding to but not saying specifically is

it's not designed to make your screen design. It's not the colors and the button shapes and necessarily even the final positioning or anything. It produces cartoons. They're wireframe cartoons. They're black and white. It's just here. Oh, they're black and white?

I gave him a hassle because I was like, why did you get a color screen if you're doing a black and white screen? But okay, now I understand. Balsamic is black and white. Balsamic is black and white. And I should take that back. Well, because I thought it was color and I didn't know why they got a color screen if they were doing black and white designs

all right anyway i am you may be able to add some color i don't remember but yeah so you can you can make these like hypercard sort of stacks where you push a button and it goes to the next slide yeah it does all the stuff so you can go through the whole flow but it's all purposely kind of uh drained of any design language it's just these this is the basic layout these are the things that will appear on the screen perhaps in the order in the various locations loosely um but it's just a great way to kind of get that first okay here's how our ui works here's how it kind of looks not saying it's going to look like this on the device or any other device. Yeah.

It allowed them to choose the correct screen size. Right. So that they... You can see how much stuff fits. They didn't try to, you know, put a book on their three-inch screen. I liked that a lot. I was impressed by how quickly they got it together and how much it explained about what they actually wanted. And it let me say, look, this is easy. This is hard.

Are you sure about this? By the way, I don't like your button names. You know, all the stuff. And for me, I have to separate it. As a user, I think this is wrong. As a developer, I think this could be better. And those aren't always even the same direction. Okay, so that's sort of part of the software spec.

Moving on. Wow, there are a lot of different documents you can have if you want. And sometimes these are all the same. You can spend your whole life doing documentation. You can spend your whole life. The software user manual. Who else is going to write it? I mean, if you're in a project like Mike is saying.

The end user manual? Right. If you have a product team, they're going to write it. Because, you know, they may have an English major. Usually that gets farmed out. Well, you know, the engineer doesn't always write the software user manual. I'd say they never do. If you're in a small company or you're on a high school technology team.

Okay. Or you're doing an open source project. Small values of never. Then you have to, it's not just how do I build this? It's how do I use this? And it may be an entirely different person and they may not be technical. And so they need the basics. If you already have your product document, moving into a software user manual may just be a matter of changing the

tenses from the software will do this to the software does this. It's one way that documenting ahead of time actually helps you document later. It's kind of addictive. Okay, so software and user manual, we've seen those. Those are easy to find good examples of. And bad ones. Probably easier to find bad ones. So easy to find bad ones. Code comments, we talked a little bit about those. Do it. Do it. Do it, but don't feel like you have to do all of it. What?

Who, what, when, why, how, where. Oh, oh. Just keep counting, you know. Just ask yourself, am I going to understand this tomorrow? The answer is no. Either think about writing it in a better way or write a comment. Or both. A year from now.

And don't forget about to-do comments. And I like to-do comments, but I also don't like them. The reason I don't like them is people tend to put them throughout the code and then, of course, never do anything. If you put them in the code with a ticket, that's better. Because then at least the ticket gets flagged in the system, and somebody coming across it can go see if somebody forgot to take the comment out, or what the ticket's about, and go fix it.

It would be nice if there were tools out there, and there probably are, to scrape your code for to-dos periodically and send the whole team an email saying, hey, you have 372 unaccounted for to-dos. 350 of them have tickets associated, 22 do not. And, you know, they can be useful, but they can also pollute your code.

But I see people doing that all the time. And I used to do them with my initials when we were on small teams. Like, okay, this is my bad. One of my compilers lately, I don't remember which one, but one of them puts fix me's as warnings. Yeah, yeah, that'd be great. Yeah. Check in comments.

They should be extensive. They should be. Well, they should be. That's hard. They should, you know, it doesn't cost anything. So usually, you know time if you have a ticket the whole thing costs time it costs a lot more time if somebody's trying to reconstruct what happened and they can't understand what your commit was about uh you know you should have

a one-liner that describes what you did with the ticket number if there's a ticket and then you should have a paragraph describing what you were fixing or what you were implementing and then maybe some bullet points. Depends on if you're squashing stuff too. Forget. So if you have eight commits for your push, each of which have one line descriptions that are good, that's maybe enough.

But again, it goes back to what would you like to see if you need to revisit the history for some reason? Do you want to see fixed bug? Yeah. Or do you want to see fixed bug that caused system to crash by releasing memory before it should have been done? I don't think that's enough. Fixed bug in module. Well, Git tells you which module.

In the log? It's not going to tell you that directly in the log if you're just looking at the whole system, the whole project log. That's true. I mean, you can do... Yeah, I mean, you can dig in, do git show for the particular commit if you want,

but it's nice to be able to see, I'm looking for when that person touched this code. And it's a lot faster if something describing what code is being changed is in the one-liner. You're writing your code comments and your check-in comments for you in one year. You're not writing them for somebody who doesn't understand the system. You're writing for somebody who mostly understands the system, but has forgotten so much because they have learned so much other stuff. It is a fine balance between too much and it's a waste of time and not enough. And you have to rewrite something

because you can't figure out how it's supposed to work. Let's see. Last thing I have. Oh, I have two more. Style guide. You should not be writing that. You should be using somebody else's style guide.

Google or Canoe or something. There's a ton of them. Pep. I don't know what that is. Python style guide. Oh, that doesn't apply to me. Let's see. iOS style guide.

I don't know. It's called Swift Lint, which yells at me. And then doesn't get all the things that people care about, apparently. And then your manufacturing document and test. This is something that firmware engineers often end up writing because they have the most visibility and because the electrical engineer has wandered off to a different project. This is to tell the person who is manufacturing it or the company who's manufacturing it how to run the tests so that they can tell if this particular piece of hardware is good or bad.

Sometimes it involves software. Sometimes it just involves running the system, making sure this light turns blue and that light turns green, and then you can put it in a box and ship it somewhere. But the manufacturing docs are helpful to you later when you have forgotten how the system works and you don't know if this board works or that board works, yeah, they need to be done. But that really is a checklist sort of document.

You're trying to say if it does this good, if it doesn't, just toss it in a bin and send it to me later. So that's the list of documentation. Mike has stopped listening, and his students have all run away because they wanted to code, not write. They went off to take journalism so that they could code more. No? Earbook? What are people blogging? Is blogging a club now? It should be a club.

Nobody blogs. Blogs went out of date 10 years ago. Do you think Instagram means a club? No. Not, no. I don't think so. Okay, let's see. Social club for your social media?

That seems kind of meta. Getting students to document effectively has always been a struggle. Either they don't do enough because they think it's a waste of time, or they do too much trying to impress. You need to demonstrate to them why it's useful. Present them with some undocumented

code and ask them to tell you what it does and give them 30 seconds. And then you hit them with the ruler, which is not done enough anymore. Mental notes. Don't let Christopher teach elementary school. We'll talk about elementary school. And the other thing that we would recommend is having examples.

There exist examples out there. I don't know that there is a full set of here's what you should do examples, but I'm going to go look and I'll put it in the show notes if I find one. Otherwise, I will try to find examples of all these documentations we mentioned. And you don't have to do them all. For professional developers, you don't have to do these all today. You should try to get them all done in the next two years. And a little bit every week will help you.

It's a heck of a lot easier if you start at the beginning, too. It is a heck of a lot easier to start at the beginning. For students, you should do the things your professor wants. You should ask the questions of which of these are most important. And if you weren't going to be working on this project in a year, well, we've talked about the ones that are important for later. Maybe skip those, but you might regret it. Ten lines of how do you actually build this thing goes really far for when you have to put it in your portfolio. All right. That is all I had. Do you have anything new? Nope.

Don't you have an announcement? Nope. About something? I do. Some musical thing? Oh, I don't know. By the time this goes up, it might be two new 12AX7 songs on the 12AX7.fm website or on iTunes, maybe on other places. But that was, you know.

We released two songs. 12AX7 is a tube. It's a band. The band came first. Don't question me. So, okay, okay. It's a band named after, before a tube that is important. Independently.

Of guitar things. Rock guitar instrumentals. Rock guitar instrumentals. They're pretty good. The tubes? No, the band. Whatever. The band consists of Christopher and his brother, and it're pretty good. The tubes? No, the band. The band consists of Christopher and his brother, and it's pretty cool. You should check it out.

Alright. Self-promoted. Happy now? Before we close this show, I'm going to remind you that we have a Patreon. Oh, did you want to announce the winners of the contest? Or we did that on Twitter?

There were some winners of the contest. Congratulations. Yay. May you hack chips. Yes. Good health. Sorry. We have a Patreon page.

If you like the show and you want to kick us a couple bucks. If you hate the show and want to kick us, say... What is your price? What is your price? If you would like to give us a couple bucks to help support the show and to give us money to buy gifts for people who support the show. Mics for guests. Mics for guests. show and more mics for guests that's the big one that's for most of the money guys hosting hosting and mics for guests are the two top line

not us hosting but uh the the whole computer you know the the the cloud where we put the podcast uh and if you do that you get access fm.fm domain names don't come cheap if you if you do that you get access those.fm domain names don't come cheap if you support us on Patreon we do give access to this Slack channel that is pretty useful

almost 200 people now or something I don't remember what it was and problems get solved and jobs get got we aren't even there a lot of the time people just talk amongst themselves. It's great. I'm there. Speck's there. Andrew's there. You're there. I just don't feel obligated to, you know,

run the place. Oh, I'm, yeah. I feel obligated to read almost everything. Well, that's ridiculous. You shouldn't do that. Oh, I have to. It's like reading all of Twitter. That I don't do. Even the people I follow.

Okay, so for those of you who already are patrons, we really do appreciate the support. And we appreciate all of you for listening. Thank you to Christopher for producing and co-hosting. And now, some Winnie the Pooh. So Pooh pushed and pushed and pushed his way through the hole and at last he got in. You were quite right, said Rabbit, looking at him all over. It is you. Glad to see you. Who did you think I was? Well, I wasn't sure. You know how it is in the forest. One can't have anyone coming into one's house. One has to be careful. What about a mouthful of

something? Pooh always liked a little something at 11 o'clock in the morning, and he was very glad to see Rabbit getting out the plates and mugs. And when Rabbit said, Honey, or condensed milk with your bread? He was so excited, he said, Both. And then, so as not to seem greedy, he added, But don't bother about the bread, please. And for a long time after that, he said nothing,

until at last, humming to himself in a rather sticky voice, he got up, shook Rabbit lovingly by the paw and said he must be going on. Must you, said Rabbit politely. Well, said Pooh, I could stay a little longer if it, if you and he tried very hard to look in the direction of the larder. As a matter of fact, said Rabbit, I was going out myself directly. Oh, well, then I'll be going. Goodbye. Well, goodbye, if you're sure you won't have any more.

Is there any more? said Pooh quickly. Rabbit took the covers off the dishes and said, no, there wasn't. I thought not, said Pooh, nodding to himself. Well, goodbye. I must be going on. Embedded is an independently produced radio show that focuses on the many aspects of engineering. It is a production of Logical Elegance, an embedded software consulting company in California. If there are advertisements in the show, we did not put them there and do not receive money from them. At this time, our sponsors are Logical Elegance and listeners like you.