You are currently viewing SemiWiki as a guest which gives you limited access to the site. To view blog comments and experience other SemiWiki features you must be a registered member. Registration is fast, simple, and absolutely free so please, join our community today!
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.
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!
...