Writing documentation

[madalin1990]

HI !

I face a problem that I think even the gurus of this comunity have faced in the past. I am referring to writing technical documentation. Supposing you have wrote some code for a module, how do you organise when writing the documentation about it?;-)

 

[mrflibble]

Interested as well. I have yet to find a good explanation describing how to do your documentation of HDL projects.

 

[madalin1990]

mrfibble do you have the time to try with me to put together a good explanation?

 

[mrflibble]

Not really. I'm not the best at writing documentation, so asking me advice on how to write proper documentation is probably counter productive. So far my strategy has been to try to get my hands on decently written documentation, look at what works and what doesn't, and then try to emulate that which works.

 

[madalin1990]

:razz: well then i'll just hang around waiting for someone to give me an idea. I have around 300 code lines, written by me, but in the last three hours I have written only 2 pages(mostly with tables). Pretty annoying I'd say!

 

[rberek]

The document that you write will vary in content depending on who your audience is. If it is for a personal hobby project, that audience is for the three-years-in-the future you so you don't have any WTF moments when you go back to look at your design. If you are an ASIC designer in a large company, working on a big ASIC, that audience might be the system architects, the software architects, the designers of the other blocks that communicate with yours, the verification people who are writing the testcases to test your RTL, the software driver writers who will be controlling and configuring your block, the backend team, etc. As you might imagine, the content required for these two audiences is very different.

Having written many, many technical documents for functional blocks, some of the common sections are:

1. Scope (what is the high level functionality of the block and where does it fit in the system)
2. Block Diagram
3. Feature Description - simple bullet list of the main features
4. Structural Description - describe each feature in detail. Use text, block diagrams, tables, timing diagrams, state machine bubble diagrams, interpretive dance, etc.
5. Hardware Interface - names of the ports, their clock speed, their direction and a short description of their use
6. Software interface - if the block is attached to a processor interface or other internal bus, describe each implemented register and the fields in each register, plus the register's address and the reset state of the register
7. Clocking - frequencies of each clock and a diagram of the clocking structure
8. Reset/StartUp - describe any unique conditions or requirements for power up
9. Parameterization - if the block contains parameters/generics to set it up (i.e. re-useable IP), then describe the name of each parameter and what it does and what are the valid values
10. Anything else your customers want to see

The RTL itself is not something I have seen included. Generally the code should be well commented and written such that it is clear and self-documenting.

My 0.02 cents.


r.b.

 

[TrickyDicky]

And I assume R.B. That the document you describe is initially written before you start coding, and then modified as the customer changes his mind!

 

[rberek]

Yup, written in advance and all of the stakeholders review and sign off on it so that no one can say "That is not what I asked for!"

Of course, being human, we forget features, or realize after simulation that that feature needs to change, or we find bugs in the device that can only be fixed by a change in your block etc. So nothing is ever carved in stone. And as the designer, it is helpful to have a guide when you write the block.

Is it fun to write? NO! No matter where you are from, what language you speak, what gender you are, what religion you follow, everyone would rather design than describe their design.

As you might imagine, I have always worked for large companies. Smaller companies may not need the rigour I described, and certainly in my hobby projects, I make notes in a notebook and make sure the code is descriptive. That's all I care to do at home!

r.b.

 

[TrickyDicky]

As you might imagine, I have always worked for large companies. Smaller companies may not need the rigour I described, and certainly in my hobby projects, I make notes in a notebook and make sure the code is descriptive. That's all I care to do at home!

They may not, but as someone who has picked up a 10 to 15 year old designs, having only been in the company 5 years, with all the origional engineers gone, having no documentation is a real pain in the arse. Especially when most of the design is AHDL and schematics with few comments!

 

[rberek]

Very true. I realized I forgot to mention the other benefit to a designer - helping to avoid the situation you fell into!

 

[madalin1990]

I already hate writing documentation . I'm on the right path of becoming a true digital designer . )
Putting the joke aside, thank you rberek, your post was truly helpful!