Re: Doc contributions
Chris Zumbrunn <chris <at> zumbrunn.com>
2006-03-02 06:46:44 GMT
On Mar 2, 2006, at 2:18 AM, Joshua Levy wrote:
> - The outline on the left column does not actually match the
> contents of http://helma.org/docs/ This is confusing. The
> left-hand side looks like a navigation tree, so it should list
> all the contents (in the same order), or just have one
> "Documents" link.
Right now I am limited in what I can do on the "old" website that is
currently online. I can't easily change the order and the hierarchical
structure of the content. The outline currently displayed is a
compromise of staying within those limitations, preventing
links/urls/bookmarks from breaking, being useful to newbies and being
efficient for regular users.
I'll make a draft version of my proposal of the "new" site available
shortly, which will address these issues.
> Generally, it can be a little hard to know what doc holds what
> information, and so you end up just clicking on many and
> reading them. This is OK, but some more descriptive names might
> help. Some ideas: Within http://helma.org/docs/,
>
> - Put "Tools" within the "Guide" folder, rather than at the top.
> (Other "tools" like HelmaDoc are already in the Guide.)
The entire documentation really should be the "Guide", with individual
sections serving as a "guide within a guide" on particular topics.
> - Rename "Reference" more descriptively as "API Reference", and
> also put it in the "Guide" folder. (There are other
> references, such as the property files reference, already
> in the Guide.)
The "Reference" I see as the exception to what I just wrote above. It
can go inside the guide, but I do not want to hide it inside the guide,
since regular/veteran users will need to use the reference regularly,
while rarely caring about the "guide" sections. At least if it is a
"good" reference - I'm thinking of making this work more like an
app/tool rather than a collection of web pages.
> - Rename "Conceptual Overview" something like "Helma Objects",
> since that is what it focuses on.
This will be rewritten and ready for the dust bin.
> - Actually, "Web Framework Guide" is closer to being a
> conceptual overview. In fact, it may be the most helpful
> thing to read first, so perhaps should be highlighted somehow.
Yes, but it needs to be broken up a bit. It currently is to hard to
digest as an "introduction".
> - The "Introductions" folder might be more accurately called
> "Helma Building Blocks" and put after the latter one.
Hmm, I see what you are saying. I'll try to come up with a more ideal
mix and structure.
> With more things within the Guide, you would know you should
> look there for general information beyond the tutorial.
> How-Tos and Examples, etc. would still be separate.
I was thinking to make HowTos/Examples a special section of the guide,
containing a collection of "quick guides" on particular problems / use
cases, separating development, deployment and maintenance related
issues.
> A couple more notes:
>
> - I see the DocBook version of the documentation, but it would
> be very helpful if there were a downloadable version of the
> web-based Guide. No doubt this involves some work to package
> it up though...
>
> - Is the Gong wiki still used much? If not, maybe remove the
> link at http://helma.org/development/doczone/ and suggest
> people use comments on the site.
Thanks, fixed.
> Well, hope some of those are of use.
Very much so, thank you. Please keep the feedback coming!
Chris
nh
RSS Feed