Parrot Documentation Review
Michael Scott
It seems to me that the problem presented by information about Parrot
is that it exists in different layers and contexts.
The presence of the docs directory in CVS is deceptive. It suggests
that it's contents are in some way definitive. But, in practice, the
docs directory is really only there to provide basic information on a
standalone machine equipped with nothing but a text editor.
In fact, information about Parrot is in various places:
On www.parrotcode.org there are FAQ, documents, links.
In the distribution there are:
- the various ALLCAPS files (plus ChangeLog) in the root directory
- the POD documentation in the docs directory
- the inline documentation in code files
On the Wiki there is search, comment, explanation, suggestions.
There's all the discussion on perl6.internals, searchable on Google.
And, last but not least, there are the CVS checkin comments.
2) Who uses Parrot documentation?
a) First time visitor
A first time visitor needs an effective introductory experience with
the minimum of frustration so that, hopefully, they will want to get
involved with Parrot and become a regular contributor.
What happens at the moment? - The new user visits www.parrotcode.org,
downloads the latest distribution from CPAN, and reads the README.
The README provides the necessary quick start, and seems to be
complemented by NEWS, KNOWN_ISSUES, etc. But, these plain text files
are prone to brevity and neglect, and the ALLCAPS naming convention
doesn't really indicate a coherent category of documents.
RELEASE_INSTRUCTIONS is of little relevance to a beginner.
So, the user proceeds to the docs directory, armed with a simple text
editor, and following the structure provided by parrot.pod and the
various subdirectories, skips or reads through the various files
according to their interest.
There is, however, sufficient explicit mention of things being
out-of-date that the authority of the documentation becomes tainted
with doubt. Also, the text format prevents the inclusion of anything
more visual than an ASCII diagram.
Dissatisfied with this documentation the user resorts to inspecting the
source code. Inline documentation is directly addressed to the
developer but it is patchy. Often the only way to get a definitive
answer is to search or post to the mailing list.
Discovering the existence of the wiki, our potential Parrot contributor
discovers editable hypertext with images. POD can be read reformated in
HTML. A lot of additional information is provided.
As one user put it:
"This is more like what I was after. All the docs in one location
and
with a decent interface for browsing through them."
b) Regular user
A regular user of the documentation is probably a contributing
developer who needs the a speedy look-up for definitive information.
What happens at the moment? - In the absence of comprehensive API
documentation, the developer has to resort to searching, either by
importing Parrot into a development environment, or by resorting to
some form of grep.
Repeated searching can be time consuming because of the guesswork
involved. The wiki also provides search, but only usefully to those
with good Internet connections. This is a problem for online
documentation too. Therefore we need comprehensive API documentation in
HTML in the distribution. Some of it can be autogenerated, not all of
it need reside in CVS. All that is needed is for there to be a clearly
defined process ensuring that each release one way or another has all
the necessary documentation.
3) Where is the primary location for Parrot documentation?
Ideally, version 1.0 will be released with complete and adequate
documentation as part of the distribution. We should continue to
improve the contents of docs until it provides the necessary minimal
documentation for Parrot. But, each release is only a snapshot of a
continuous process, and it is this real world process that the
documentation primarily serves.
Given the presence of www.parrotcode.org and the wiki (proposed by
Robert to be wiki.parrotcode.org), the information included in a
release is always really only relevant in the context of a standalone
machine.
The effective primary location for Parrot documentation will always be
*.parrotcode.org. What goes into the distribution should therefore be
derived from - or at least closely reflect - the content there.
4) Why would anyone volunteer to be responsible for Parrot
documentation?
I would not be involved in Parrot if it were not for Piers and his
weekly summaries [1]. They gave me the sense that what seemed opaque
could become clear with some attention and effort. How many potential
contributors have been lost to Parrot simply because they lacked the
time to get over the initial learning curve? Frustrated by the state of
the documentation they lost interest. That's the problem I want to
solve.
5) Parrot documentation person
Last week on TV they showed something that looked a bit like a cake tin
scurrying around the furniture sweeping up - a vacuum cleaner robot.
That's the image I had in mind when I talked of "a semi-autonomous
process with clearly defined protocols and goals".
Dan has agreed to get me "general checkin privs". Once that's set up
I'll start working my way through CVS and getting things in order
documentation-wise. I'll announce what I'm going to do beforehand on
the list with a [DOCS] prefix on the subject so you can ignore it if
documentation isn't your thing. After a couple of days I'll take
silence as consent and go ahead and do what I've announced.
When I was putting together the Getting Started Guide I hesitated to
pester the list or individuals with questions because, in general, I
found if I persisted I learnt more. This will probably change, I expect
I'll have to try and extract pithy little summaries from some of you
every so often. But I promise I'll leave the chastisement to Melvin.
Footnote
[1] I wrote this over the weekend and was waiting for Piers to post his
summary before I posted it - having fallen into the crack between
summaries before. Little did I expect that the crack would become a
chasm.
I would volunteer to step in and fill the gap were it not for the fact
that I'm off to Finland tomorrow for the week, and will be
computerless. So, all I can offer is this rather feeble thing called
sympathy, Piers.
Mike