I have written software for an embedded system. All commands are received b y UART. Now I must create a document that describes the software and how it works together with the hardware on that circuit board. Someone else shoul d feel comfortable reading this and start to make future modifications to t he software. How do I get a good structure in that document? Where to begin? I figure I must at least include the following:
*Describe the purpose of the software (what does it do)
Describing to MCU (short info about the MCU, type, clock frequency, compi ler used, maybe an example how to start make a change, compile, flash the M CU and debug).
A table of the MCU IO-pinning used.
Some sort of block diagram of the circuit board.
All commands used on the UART
A sequence diagram of the UART commands
More in detail descriptions of my code for UART, SPI and so on.
How do you usually do it?
And what are these kind of documents usually called?
You should have STARTED with this document. In that way, *YOU* would have felt comfortable CREATING the software in the first place! You would have known "where you were going" before starting the trip; instead of figuring out "where you have arrived".
[THINK about that.]
Much of what you have described can be handled with copies of manufacturers' datasheets. They know far better than you how to describe their product -- in excrutiating detail!
Concentrate, instead, on the value that you have added: the application that you have coded, the process that you have followed to craft the software, implement it and TEST it. Think of the notes that you would leave FOR YOURSELF if you assumed you would have to come back and revisit this project many years from now (without having seen it in the intervening time).
An often neglected bit of documentation is a roadmap that indicates what is implemented in each file (in general terms) as well as something that gets the future reader *into* the code "from power up" -- where is the first instruction that is executed? The second? Why? What do they do? Where does the application proper begin??
Well I would call it Software Description. Don's a bit hard on you because you didn't write this first and to a large extent I agree with him. I don't agree with him that it's a Specification.
Why - because the specification is a formal promise (to the customer) of what is delivered but there is no reason at all that it should tie down internal details.
The Software Description is intended (as you said) to help maintain the code later.
I find the best way is to work from spec, requirements, data sheets etc to plot out my plan in a notebook but as soon as it starts to take shape I start writing the SD - that way I don't end up writing it twice.
If I'm designing a comms protocol I define all the messages in the document before I code them. It's not uncommon for someone else to be writing the other end's code at the same time.
I use the same process with FPGA design (which I do more often than code) and then I call it an FPGA Description.
It isn't unusual for these description documents to change and evolve during the process (unlike Specifications again) - I have current projects where we are up to issue >20.
Yes, I was being deliberately intense: you want to tell OTHERS what you did -- yet no one told YOU what to do? (where's the logic in that?)
A Specification can take many forms. I used to write very dry documents with fine "shall/should/may" distinctions and explicit declarations of requirements -- from which deliverables could be verified.
But, this takes a lot of time and is only used "to keep honest people honest" (by providing a contractual document that all parties can use as final arbiter).
Nowadays, I write a User's Manual that describes how the product *will* work. As a user's manual should answer ALL questions that a user could pose ("What does this error message mean? How do I recover from it?"), the manual effectively addresses every aspect of the product's design but in a more colloquial manner than a Formal Specification.
In developing that document, I envision what sorts of technologies I will use to implement the product (or portions thereof). As these are often very application specific (i.e., not particularly known to a "typical developer"), I prepare short (15-30pp) documents that act as tutorials ("brain dumps") to help bring others up to speed as to the underlying technology in my implementation.
E.g., I use cubic Bezier curves extensively in my gesture recognizer. Yet, assume most folks have only cursory exposure to them and are probably unaware of the various pathological cases that can exist -- or how they can affect OTS algorithms. Nor the costs and tradeoffs of various approaches to implementing and analyzing them (what's the most efficient way to DRAW a Bezier? Given a set of control points, what will the curve look like -- without drawing it?)
So, I prepare documents that present this information in a manner that allows others to see why I've made particular choices in the implementation and why the algorithms act the way they do (without having to add lots of commentary in-line to explain caveats mentioned in the tutorial)
+1 That's the whole point of describing what you are going to do BEFOREHAND. Otherwise, you end up with a piece of code that has "evolved" -- often in ways that are not self-consistent (e.g., handling a problem one way "over here" and a similar problem another/better way, "over there").
More importantly, it lets others look at your thinking before you start down a wrong path. They can spot inconsistencies or outright errors that you may be blind to (because you are too close to the problem/solution).
I had a colleague develop a very elaborate approach to a particular instrumentation problem -- one that he was "tickled" with! Yet, when I looked at his proposal, there was a glaring flaw on "page 1" that invalidated his entire approach. :< He'd long previously accepted that premise as a Given and never reexamined its validity...
You first consider what purpose you want the document to serve and who you expect to read it. Clearly state that in words at the start of your doc. Then proceed to write more words in an organized fashion that keeps with the ideas expressed in your first statement.
It's just that simple. It looks like you have a good list. It's what on your mind and I presume you want somebody else to know that information too.
A SW description doc is as good as anything else. In reality it really doesn't matter what you call it. If your company or customer has any naming requirement then use that. Call it what you think it is.
Believe me when I say that in this day of poor or missing documentation (a severe affliction at my work place), it'll impress just about anyone if it's useful.
When to begin is more important -- before you start writing code is generally accepted as best.
The things you're commenting on are all generally found in different documents. I assume that these are all missing:
This would be found in the introduction to a software architectural design document, or in a system design document.
The MCU type, clock frequency, IO pinning, and circuit board block diagram should all be found in the board circuit design document.
"How to start to make a change" is kind of implied in the job description of a software engineer. A proper software design document would tell a competent software engineer HOW the software is designed, and to some extent WHY, but if someone can't read that document, look at the code, and figure out where to go from there, then they should probably move into management, or start flipping burgers for a living.
How to compile, flash the MCU and debug, would be either a deployment document, or engineer's notes someplace. Again, this should be easy for a competent software engineer to figure out.
If you mean the commands present on the asynchronous serial lines, then this would go into a communications protocol document, which would either describe the whole protocol and the data dictionary (if the protocol is small) or just the protocol, with a separate data dictionary (if the protocol is large, or if it is used in more than one product).
Communication protocol document.
Software design document.
By writing the document first, then designing to it. You can't do this
100% -- but you generally at least try to edit the document as you write software.
It sounds to me like you're writing this document because someone asked you to, yet you have no idea why it was asked.
This sounds like an excellent chance to plug my latest book! Or at least the latest book that has content of mine in it. It's called "Developing and Managing Embedded Systems and Products: Methods, Techniques, Tools, Processes, and Teamwork" by Kim Fowler, Craig Silver, etc. -- I'm one of the etc. It covers ALL of project management, but that includes outlines of the proper process for developing each bit. Here's a link:
You should probably also google around with various key words on the order of "software development process" or "embedded systems development process" (since you're without a board circuit description, either).
There's also one other thing the OP should do here and that is to keep, at an absolute minimum, a list of the URLs for the manufacturer's datasheets/reference manuals used in this design and make it available in the OP's document.
Far better however is to keep a _permanent_ local archive of the exact version of each manufacturer's document used during development.
The latter approach is the one I use (and I do this even though I'm just a hobbyist here) so that when there's a site reorg or someone goes bust or gets taken over, I still have the document to hand. I download the document when working on a project and it gets placed in a permanent archive when I am finished with it instead of being deleted.
Simon Clubley, clubley@remove_me.eisner.decus.org-Earth.UFP
Microsoft: Bringing you 1980s technology to a 21st century world
URL's rot over time. Take the time to acquire (and preserve) copies of any documents on which you rely. Ideally, these are PDF's (or, any other self-contained document format). It's a real drag to have to pull down a large portion of a web site because the document is only available as an endless series of HTML pages!
The downside of this is it doesn't take long for you to end up with a whopping HUGE archive! (you don't want to know how many TB I've got squirreled away -- on differing media for robustness, etc.)
In *theory*, you can just include this with the rest of the deliverables for a particular client/customer. In *practice*, I've found that clients are terribly careless with these sorts of things -- "misplacing" documents, sources, etc. So, learned to keep my own copies of everything delivered "just in case".
by UART. Now I must create a document that describes the software and how it works together with the hardware on that circuit board. Someone else sho uld feel comfortable reading this and start to make future modifications to the software.
piler used, maybe an example how to start make a change, compile, flash the MCU and debug).
HLD(High Level Design) document - This gives the overall system architectur e/design . It provides a high level view of the all components/modules of t he system along with the high level relation and communication mechanism be tween them. The overall system block diagram shall also be part of this doc ument.
LLD - Low Level Design Document - This takes the design to the next level b y providing granular details of the design of the various entities of the s ystem. It will have clear details about the interactions between components and also logic used in various routines. It shall also tell the relation b etween the different modules in a very finer way, exact level of memory use d, memory map details, pin details and also spec level details. Diagrams el aborating the sub systems shall also be present here.
User Manual - This gives detailed steps to bring-up the system and use the application.
Product specifications: this tells the customer what the product does as a "black box". If you're selling to a military or other highly technical customer, the product specifications becomes the technical part of the contract between you and the customer . If the customer supplies your equipment with everything that you specify that it needs, then your equipment is expected to supply everything that the specifications say it will.
Product specs can sound bad (Omigod, I have to make it work to XXX). However, they're also the vehicle by which you can avoid unreasonable customer demands -- if the product specification is, essentially, "make Rosco happy", then you've just written an open-ended contract to deliver potentially unlimited work. If you were foolish enough to do so in a fixed-price contract, then SOMEONE is going to end up bitterly disappointed at the end of the process.