IP doc - there must be a better way to do it!

[AndyBetts]

I have just spent 3 weeks reading technical documentation on various RTL IP. Please help me recover the will to live ...

My impression after reading most of the docs was: "Ok, so I understand what the thing is now - but why is it like that and how do I use it?".


Any shining counter examples out there, or thoughts on how to improve the situation?

PS. Modern editing technology seems to make things worse, as a lot of text is generated/included automatically, leading to zillions of short sections and creating a hard-to-read flow.

 

[mwipliez]

Hi Andy,

I think that a way to improve the situation is to have IP in a language that is higher-level than RTL, like C~ (see https://www.synflow.com/tech and https://www.synflow.com/tech/documentation/c-flow/examples ). An additional advantage is that block diagrams are not decorative, they are part of the design (e.g. https://www.synflow.com/tech/documentation/design/ with input ports 'ready', 'isValid', 'frame_i', and output port 'frame_o'). I don't know what you would like to see in technical documentation, but I'm pretty sure we can do a better job of generating quality documentation with C~ than with RTL

As a matter of fact, it would be interesting to investigate automated documentation generation in our tool!

Cheers,
Matthieu