Re: [myhdl-list] Documentation doubts

[<dan...@we...>]

Jan Decaluwe wrote:
> Hi all:
> 
> I am currently updating the documentation for release 0.5.
> With the 0.5 release, I hope to attract new users.
> 
> However, I'm not sure the current set of docs is adequate
> for new users. Pointing to the whatsnew document and the
> manual may be overwhelming.

I think it always depends on the background of the new user. Basically
there are two components to that, one is the Python knowledge and the
other the HDL knowledge.

Having someone with strong HDL background, but a new MyHDL user the
current manual might be just sufficient. Speaking for myself I find it
now sufficient and I like that it is so concise. From my background I
would say I have more experience with software development and Python
than with HDL development. However, Python generators were something new
to me and getting used to. I am still not used to using them in software
development. Concerning HDL development I am pretty much a beginner.

I had to read the manual several times in order to understand it, every
time finding something new that I overlooked the first time.

I was always reading it, in my mind looking for a way to use MyHDL as a
tool to develop synthesizable HDL. It was only later that I recognized
that most of the examples given are more towards verification and only a
small part was for generating synthesizable HDL. When I look now at the
manual I would say it is clearly said so. But also it is pretty
interwoven. I wonder whether a separation of the manual in terms of
verification and synthesizable HDL would help to clarify that?

> 
> I'm not asking for addition work :-) but shouldn't there
> be some kind of Getting Started document? E.g. taking
> a simple example all the way to Verilog.

I think that is almost there with the rs232 example. For now it covers
just verification. To emphasize the synthesizable HDL part this could be
extended to that, at least in parts.

> 
> As you have all been new users at one point, perhaps you
> have some ideas on what was missing (if anything) to get
> you on track asap.

As I said earlier, it is nice now to have the manual being concise. At
the beginning I had hoped to have some additional information. I often
thought about it would be nice to have something like a  'tips and
tricks' area on the wiki where users would add their 'aha'-experience.
To some new users they might be useful information, but too much for the
manual.

[...]

Just my two cents.

Guenter