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
