Parrot Documentation Review - perl.perl6.internals

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
perl.perl6.internals
Message from discussion Parrot Documentation Review
Newsgroups: perl.perl6.internals
Path: archiver1.google.com!news2.google.com!news.maxwell.syr.edu!newsfeed.stanford.edu!nntp.perl.org
Mailing-List: contact perl6-internals-h...@perl.org; run by ezmlm
Mime-Version: 1.0 (Apple Message framework v606)
Content-Transfer-Encoding: 7bit
Message-ID: <47906C10-1959-11D8-AC7B-0050E479991D@mac.com>
Content-Type: text/plain; charset=US-ASCII; format=flowed
To: perl6-intern...@perl.org
Subject: Parrot Documentation Review
Date: Tue, 18 Nov 2003 00:53:45 +0100
Approved: n...@nntp.perl.org
From: michael_sc...@mac.com (Michael Scott)
Lines: 151

1) What is Parrot documentation?

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
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
