Array
(
    [content] => 
    [params] => Array
        (
            [0] => /forum/index.php?threads/ip-doc-there-must-be-a-better-way-to-do-it.3270/
        )

    [addOns] => Array
        (
            [DL6/MLTP] => 13
            [Hampel/TimeZoneDebug] => 1000070
            [SV/ChangePostDate] => 2010200
            [SemiWiki/Newsletter] => 1000010
            [SemiWiki/WPMenu] => 1000010
            [SemiWiki/XPressExtend] => 1000010
            [ThemeHouse/XLink] => 1000970
            [ThemeHouse/XPress] => 1010570
            [XF] => 2021370
            [XFI] => 1050270
        )

    [wordpress] => /var/www/html
)

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

A

AndyBetts

Guest
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.
 
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
 
Back
Top