How to write a software description document?

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.