On Tue, 28 Oct 2014 10:31:30 -0700, Karthik Balaguru wrote:> 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.Add to that: 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. -- Tim Wescott Wescott Design Services http://www.wescottdesign.com
How to write a software description document?
Started by ●October 24, 2014
Reply by ●October 28, 20142014-10-28
Reply by ●October 28, 20142014-10-28
On 10/28/2014 10:31 AM, Karthik Balaguru wrote:> 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. >http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form It's very old technology. Probably more automated versions now. But worth a look at the concept. Once it's in BNF, there's no ambiguity about what it does.
