Parrot's Documentation set

[Brian Gernhardt]

Here's my $0.02:

On Oct 26, 2011, at 11:56 AM, Alvis Yardley wrote:

> (1) An overhaul of the parrot.org website;

The biggest thing I think parrot.org needs is a friendly front page.  The news being right up front is nice, but even nicer would be a "Welcome to Parrot, here's what it is, here's how to get started, and here's how to get more help."  perl6.org and git-scm.com are decent examples of what I mean.

> (2) How best to organize the documentation set;[6]

> [6]  For example, one obvious division quickly springs to mind: Clear, unambiguous, user-visible demarcation points among Parrot's feature set; its internals; its various APIs; its HLL developer support; its ....  Another is a division between "core" documents and user-contributed wikis.


I think we need to make two clear divisions in our documentation.  (Which we currently make, but not clearly enough.)

- reference vs explanatory
- user vs developer

Reference documentation is what exists, what its for, and how to call it.  It needs to be as close to the code that it documents as possible.  (IMHO, a major reason that PCT's documentation is so out dated is that it is so far away from the code.)  This needs to remind people who know Parrot of the details they need to use at the moment.  The people who are updating the code need to update the documentation.

Explanatory documentation is the introductory, tutorial, and the why and how things work.  This needs to be beginner-friendly and avoid repeating too much of the reference.  It should be updated by anyone who can explain how to grok Parrot better than what currently exists.

User documentation is what an external developer needs to know about parrot:  embed, extend, PIR, PCT, PMCs, etc.

Developer documentation is what an internal developer needs to know to work on parrot:  GC, strings, runloops, etc.

Right now, all four types are just lumped together in a big mishmash of documentation.  I would personally say that the reference documentation should be generated directly from the source and the user documentation can be more open, probably in a wiki.  (With internal and external being separated in each section.)

A good automatically generated index would also be fantastic.  (A good manual index or a decent automatic one would be nice, but fall short of fantastic. ;-)

> (3) Where best to house our documentation set;

Mainly I think that that we have some divisions currently that hurt instead of help the project.  We have at least four separate logins that have nothing to do with each other:

- Github organization membership:  For committing to our code
- Trac:  For contributing to our old wiki and tickets
- Drupal:  For editing content to parrot.org
- FTP: For editing content on docs.parrot.org

Ensuring that everyone who needs access to the various portions of this infrastructure is difficult at best.  I refer you to the constant troubles of the release managers being able to update everything they should be able to.  Even long-time participants have problems (e.g. dukeleto needing help to upload tarballs and documentation for Parrot 3.9).

Given that we seem to currently be attempting to center around the community focused tools on github for development, it seems natural to use the additional tools provided for webpages.  http://pages.github.com/ describes their tools for web pages, and it appears we can use it to host parrot.org, complete with per-project documentation, blog posts, and global styling.

> (4) The form in which to store the documentation, e.g., plain text, pod, markdown, etc.; and

> [8]  I have read through some (most I think) of the archived email, addressing this lack-of-uniformity issue, and I get it has been, in the past, the source of a "religious war"-type thing, but we, as a community, simply must come to terms and resolve this outstanding issue.  It is very disruptive and very confusing for a new developer.  He or she wonders, especially during the first week or two, while trying to figure things out, "Why this lack of uniformity in simple READMEs?"  And, then, he or she spends several, unproductive hours digging around only to find, "Oh, it's a "religious war" kind'a thing."  It's very unhelpful.

I'm not sure this is a real issue.  As long as it is clear what format each file uses, does it matter how many formats we use?  When I dive into a project, as long as there's a clear way to read the documentation, I couldn't care less how it's stored.  I still tend to use docs.parrot.org for reference far more than anything on my filesystem.

I would note something I ran across on trac:  I would be very good if we generated a manpage for each binary we install as part of parrot.  It doesn't have to be a required part of the install (it's less likely to be useful on Windows), but having it there as an option will make parrot a little bit friendlier (and make Debian happy).

> (5) Whether or not to make concerted efforts to locate and to identify out-dated, but still valuable, documents about Parrot, e.g., the PIR Guide (and related) *.pds, Allison Randall's video presentations, etc., and properly archive them with something like, a *WARNING: THESE DOCUMENTS ARE OUT OF DATE* tag.

I'm not sure we need to find _all_ documentation about Parrot, but it should probably be high priority to mark everything of ours as out of date where needed.  (And to update it, of course.)  There may be a few other high-visibility things we should hit like the Parrot VM WikiBook[1].  Archiving out of date things within *.parrot.org is probably not really useful, but figuring out what the valuable parts of the other things you mention and including them in our own documentation is probably a good idea.

[1] http://en.wikibooks.org/wiki/Parrot_Virtual_Machine

~~ Brian Gernhardt