Ask HN: How can code documentation be improved?

A lot of embedded systems documentation is in PDF format. e.g. each processor will have a datasheet that gives a quick summary of the part's features, and reference manual that describes the interfaces in more detail.

PDF is a nice format. It means you can have all the documentation saved locally. But most of the time it would make no difference if the documenation was on the web, and being able to see metrics about which pages are most visited would probably help both the writers and the users. There are probably additional features (like better search, or Q&A forums linked to the documentation) that could be provided on the web that aren't available in PDF readers. Users might also learn about changes in documentation more frequently. Some companies like Nordic already provide web-based documentation.

Another issue: Companies will buy verilog libraries to use in their SoC. And the documentation for those libraries comes along with them. But the support and Q&A for these libraries is handled separately.

e.g. Companies A and B both sell SoCs, and both purchased the verilog code/documentation for their I2C peripherals from Company C. A and B include C's documenation in their manuals as if they wrote it. Then they run separate support forums where users unknowingly ask the same questions about C's library. It would be more efficient if there was just one support forum.

The hardest part about this question is that “code documentation” is a very vague concept. Are we talking about an API document for programmers who are using the code, calling its functions? Are we talking documentation for users of the application that this code implements? Are we talking about documentation for someone who will be maintaining the code? Some other type of documentation? What problem are you really trying to solve with this documentation?

Once you answer that question then you can start to figure out the best way to document it.

Ask someone outside your team to explain your code based on documentation/structure. If they can clearly explain what you intended the code to do, you should be good.

I would say that the main thing is for companies/management to slow down. If we're always expected to be jumping to the next thing to deliver, deliver, deliver, then when do they think we have time to document code, create prod support documents, etc?

1) Code reviews 2) At the code review, have someone who will inherit the code. let them know they are inheriting the code and that they should make sure it is well done. 3) The person inheriting the code should also be passing code to the other person to maintain.

Literate Programming