PARROT'S DOCUMENTATION SET: A (Tentative) Plan of Attack parrot-users <parrot-users at lists.parrot.org>

[Brian Gernhardt]

My quick $0.02:

On Nov 1, 2011, at 8:55 AM, Alvis Yardley wrote:

> 
> (1)  The new Parrot documentation set will, of course, reside on Github,
> whether in a branch or on a separate repo, I do not know.
> 
>     Note: I need direction on this.  It seems to me a branch to the master
>     should suffice, but I do not, as yet, sufficiently understand Github to
>     assess whether or not this is the correct approach.

I would say that it's better to keep the documentation close to the code.  Then at least there's less of a barrier for coders to work/check the documentation and people working on documentation have ready access to the source.  If the documentation becomes overly large or we start doing things like collecting translations, we can split it off later.

> (2)  All documentation housed on Github will, of course, be formatted in
> conforming Pod.
> 
>     Note: Presumably in Perl5 Pod, but I am not entirely certain.  By which I
>     mean, I see no reason to transition away from Perl5 Pod to Perl6 Pod, but
>     I have yet to hear from others, and I am open to arguments. 
> 
>     This may, in fact, be a non-issue: Does Github even speak Perl6::Pod?  If
>     not, that settles the matter.

I don't think Github speaks Pod (P6), only POD (P5).  Plus, to develop Parrot, you need Perl 5 (and therefore POD) anyway.

> (3)  In-line with Brian's (Benabik's) recommendation, we will divide Parrot's
> documentation into three, separable, but, of course, related documentation
> sets:[5]

> [5]  Brian's post could be (perhaps "should") read as recommending four, not
> three, sets of documentation.

I just wanted to point out there are four problem domains.  They can be split up in whatever fashion is useful.  :-)

> 
>     (1) A Developer Manual - which will consist of an explanatory Part I and 
>     an applicatory Part II.
> 
>     (2) A User Manual - which, similarly, will consist of an explanatory Part
>     I and an applicatory Part II.
> 
>     (3) A Reference Manual - which details, specifically, Parrot's
>     implementation.[6]

Particularly, this split makes sense to me.  The reference manual should have natural divisions between Developer (internal APIs) and User (PMCs, Ops, extend/embed, etc).

> (4)  I will write an autogen indexer for the index to the above;
> 
> (5)  I will also write the manpages to the installable binaries;[7] and
> 
> (6)  I will write a new, friendlier front page to parrot.org.[8]

That's a lot of "I will".  I very much appreciate the dedication, but please reach out for help before burning yourself out.  :-)

>     Note: I need some direction on the PIR book.  Do we need to update it?
>     By which I mean, do we need to expend limited resources on updating the
>     PIR book?  Or, to put it differently, are we going to support PIR for say
>     ... the next five or ten years?  Or will it disappear?

PIR is probably going to exist for the foreseeable future.  IMCC may be replaced by an in-VM compiler or we may grow alternatives, but it's the major method of writing code for Parrot at the moment and there is no clear replacement at the moment.

>     	   I also need some direction on PASM.  That is, to what extent do we
>     now cover PASM?  Or, equally, do we drop all coverage of PASM in favor of
>     M0? And, if so, what direction can anyone, cotto, dukeleto, whiteknight,
>     give me on M0? 

As far as I know, PASM is a dead format.  Bothering to update documentation for it doesn't seem particularly useful.  We may want to include some reference documentation for whatever bit of it still exists, but there's probably no need to explain it to new users.

> In addition, there are things which, at this time, I simply do not know how to
> handle.  For example, I have absolutely no idea on how to handle user
> contributions, which, obviously, are an important part of Parrot's
> development. So, suggestions welcome!

Keep the documentation source on github and document the documentation process.  :-D  Maintaining a TODO list/issue list for the documentation may help as well.

> [3]  For example, I am presently working on my implementation of my HAMT, and
> while Whiteknight was good enough to suggest I look at his data-structures
> project, I still am unclear as to how, exactly, to integrate this
> data-structure into Parrot.  In addition, I'm playing with Ken Thompson's
> implementation of NFA Regular Expressions, and, I think, I want to integrate
> it into my ClojurePVM implementation.  So, is it a PMC or a dynpmc?  Or, does
> it belong in a library, and I make a NCI call?  How do I know which is the
> correct approach?  (Other than, of course, asking someone on #parrot, which,
> in-and-of itself, is a'bit ... off-putting.  Not, I hasten to add, because of
> anyone on #parrot, but because it's something I should be able to figure out
> with the proper documentation.)

Most data structures are good candidates for PMCs.  The difference between PMC and dynpmc is whether or not it's baked into the main parrot library.  I'm a big fan of keeping the core small, so a dynpmc sounds like a good plan.  Better data structures would be awesome, and I'd especially love to see a NFA regex engine in core.

~~ benabik