Why you need good documentation for your VHDL and Verilog code

In this blog series, guest blogger Smrita talks about the need for documentation for complex RTL designs.

In engineering, technical documentation  refers to any type of documentation that describes handling, functionality and architecture of a technical product or a product under development or use. The intended recipient for product technical documentation is both the (proficient) end user as well as the administrator, service or maintenance technician. In contrast to a mere “cookbook” manual, technical documentation aims at providing enough information for a user to understand inner and outer dependencies of the product at hand. The technical documentation is intended to help the maintainers of the system (the people who need to keep the system running smoothly, fix problems, etc.) The maintainers are usually technical people, who need to know exactly how the system works .

In other words, Technical documentation is quite simply the compilation of documents which aim to describe a technical product. Technical documentation is characterised by its systematic and structured framework.

Introduction

Code documentation is an important aspect of both software and hardware projects and all general principles of software engineering can be applied to text-based (or: RTL-based) hardware design in such languages as VHDL, Verilog and SystemVerilog. Scott Ambler describes a software document as “any artifact external to source code whose purpose is to convey information in a persistent manner”. When engineering software or hardware, the code alone is insufficient. There must be text along with it to describe various aspects of its intended operation. It is important for the code documents to be thorough, but not so verbose that it becomes difficult to maintain them. Several How-to and overview documentation are found specific to the software application or software product being documented by API Writers. This documentation may be used by developers, testers and also the end customers or clients using this software application. Today, we see lot of high end applications in the field of power, energy, transportation, networks, aerospace, safety, security, industry automation and a variety of other domains. Technical documentation has become important within such organizations as the basic and advanced level of information may change over a period of time with architecture changes. Hence, technical documentation has gained lot of importance in recent times, especially in the software field .

Benefits of documentation for software and hardware code

By definition a complex hardware design is difficult to understand  and needs to be documented well. The purpose of technical RTL documentation is to help the intended audience understand the product and accomplish various tasks. For example, the purpose of a document can be to help the audience install the product, use the product, or administer the product. The main focus lies in the step-by-step process to deliver the technically complex information in a clear, concise, simple, consistent and usable manner. This helps inform the target audience about the technology in the most appropriate format.

We have all been frustrated at times when we are not able to understand the features of a product, or when the user interface layout is not explained well enough. One problem with unorganized information is it can’t be found, so there is a lot wasted time spent pecking around looking for the right document or trying to find the right person to talk to. Another problem is if your documentation can’t be found, then redundant functionality is often created, that result in waste of time.

The real benefit to the organization of documentation is reducing wasted time and spending more productive time on projects. This, of course, improves profitability.

Another benefit to organized documents is the ability to reuse parts of the application documentation .

Other benefits of documentation for RTL hardware designs can be listed as follows:

• Doesn’t change over time: This is one of the primary drives for creating documentation.
• Person independent: You do not need to have access to a particular person with the right knowledge to retrieve the documentation; you can just look it up.
• Scalable: In a pure person-to-person approach to information sharing, you’ll quickly find a small subset of project members using a great deal of their time explaining project aspects to other project members. This can be alleviated somewhat by first attempting to looking information up in the project documentation, before turning to the project oracle in the particular area of interest.
• Geographical invariant: If a project team or stakeholders aren’t all placed at the same location, the barrier to person-to-person information exchange rises significantly, thereby making documentation based information exchange more attractive. This is of course only the case if the documentation is accessible at all relevant sites, eg. properly Internet based, or at least intranet based.
• 24/7 accessibility: Documentation based information can be access all the time. So even when project members have different working hours, vacations etc. they will still (in principle) have access to information generated during their absence.
• Reference information: Where person-to-person information exchange usually varies according to the context it is used in, documentation based information never changes unless somebody actively updates the documentation. This makes documentation a more stable reference platform, than person based information, which has a tendency to vary more depending on who is delivering the information when. The variations in the information consumers interpretation  of the information provided is of course another matter.

Technical documentation is beneficial for the organization too. It creates a good impression on new customers because this is the customer’s first touch point after the sale. It helps the customer make decisions related to the purchase of the full product or its features, and informs the customer about the instructions and troubleshooting tips that are essential for ensuring a great customer experience, which can reduce customer support costs. Also, technical documentation provides good product knowledge to the customer that increases chances of finding greater functionality in the product, and enables customers to avoid errors, thanks to accurate and clearly-written procedures .

Hence, good technical documentation is very essential. It can provide a better understanding of the product and prevent customer errors, making business processes more reliable.

Coming up

Next week we’ll discuss: How much time is spent on writing documentation versus developing RTL code?