Forums

How to write a software description document?

Started by Unknown October 24, 2014
I have written software for an embedded system. All commands are received 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 should feel comfortable reading this and start to make future modifications to the 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, compiler used, maybe an example how to start make a change, compile, flash the MCU 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?
On 10/24/2014 4:51 AM, skolpojken72@yahoo.se wrote:
> I have written software for an embedded system. All commands are received 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 should > feel comfortable reading this and start to make future modifications to the > software.
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.]
> 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, compiler used, maybe an example how to start make a > change, compile, flash the MCU 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.
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??
> How do you usually do it?
Before writing the code in the first place!
> And what are these kind of documents usually called?
Specifications.
On 24/10/2014 12:51, skolpojken72@yahoo.se wrote:
> I have written software for an embedded system. All commands are received 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 should feel comfortable reading this and start to make future modifications to the 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, compiler used, maybe an example how to start make a change, compile, flash the MCU 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? >
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. Michael Kellett
On 10/24/2014 8:39 AM, MK wrote:
> On 24/10/2014 12:51, skolpojken72@yahoo.se wrote: >> I have written software for an embedded system. All commands are received 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 should >> feel comfortable reading this and start to make future modifications to the >> software. >> How do I get a good structure in that document? Where to begin?
>> How do you usually do it? >> >> And what are these kind of documents usually called? > > 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.
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?)
> 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.
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)
> 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.
+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").
> 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.
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... [Better to find it before he'd implemented it!]
> 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. > > Michael Kellett > >
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.

JJS

On Fri, 24 Oct 2014 04:51:33 -0700, skolpojken72 wrote:

> I have written software for an embedded system. All commands are > received 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 should feel comfortable reading this and start to > make future modifications to the software. > How do I get a good structure in that document? Where to begin?
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:
> I figure I must at least include the following: > * Describe the purpose of the software (what does it do)
This would be found in the introduction to a software architectural design document, or in a system design document.
> * Describing to MCU (short info about the MCU, type, clock frequency, > compiler used, maybe an example how to start make a change, compile, > flash the MCU and debug). > * A table of the MCU IO-pinning used. > * Some sort of block diagram of the circuit board.
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.
> * All commands used on the UART
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).
> * A sequence diagram of the UART commands
Communication protocol document.
> * More in detail descriptions of my code for UART, SPI and so > on.
Software design document.
> How do you usually do it?
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.
> And what are these kind of documents usually called?
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: <http://www.amazon.com/Developing-Managing-Embedded-Systems-Products-ebook/ dp/B00NEKGZEI/ref=sr_1_2? s=books&ie=UTF8&qid=1414185468&sr=1-2&keywords=embedded+systems+project +management> 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). -- Tim Wescott Wescott Design Services http://www.wescottdesign.com
On 2014-10-24, Don Y <this@is.not.me.com> wrote:
> On 10/24/2014 4:51 AM, skolpojken72@yahoo.se wrote: >> 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, compiler used, maybe an example how to start make a >> change, compile, flash the MCU 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. > > 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! >
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. -- Simon Clubley, clubley@remove_me.eisner.decus.org-Earth.UFP Microsoft: Bringing you 1980s technology to a 21st century world
On 10/24/2014 7:17 PM, Simon Clubley wrote:
> On 2014-10-24, Don Y <this@is.not.me.com> wrote: >> On 10/24/2014 4:51 AM, skolpojken72@yahoo.se wrote: >>> 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, compiler used, maybe an example how to start make a >>> change, compile, flash the MCU 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. >> >> 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! > > 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.
[turned up nose]
> Far better however is to keep a _permanent_ local archive of the exact > version of each manufacturer's document used during development.
+42 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 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.
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".
Thanks for your shared experience and comments. I will look for that book also.
On Friday, 24 October 2014 17:21:38 UTC+5:30, skolpo...@yahoo.se  wrote:
> I have written software for an embedded system. All commands are received 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 should feel comfortable reading this and start to make future modifications to the 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, compiler used, maybe an example how to start make a change, compile, flash the MCU 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?
HLD(High Level Design) document - This gives the overall system architecture/design . It provides a high level view of the all components/modules of the system along with the high level relation and communication mechanism between them. The overall system block diagram shall also be part of this document. LLD - Low Level Design Document - This takes the design to the next level by providing granular details of the design of the various entities of the system. It will have clear details about the interactions between components and also logic used in various routines. It shall also tell the relation between the different modules in a very finer way, exact level of memory used, memory map details, pin details and also spec level details. Diagrams elaborating the sub systems shall also be present here. User Manual - This gives detailed steps to bring-up the system and use the application.