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

[Alvis Yardley]

	PARROT'S DOCUMENTATION SET: A (Tentative) Plan of Attack[*]


If there is one uniform, opinion about the current state of Parrot's
documentation it is, Parrot's documentation is inaccessible.  This
inaccessibility is due to a multiplicity of factors, to include

(1)  Out-of-date documents (both within Parrot's repository and "out" on the
     net, e.g., Wikibooks);

(2)  Incomplete documents (e.g., '/docs/compiler_faq.pod');

(3)  Inconsistent documents (e.g., the documents on doc.parrot.org do not, in
     many cases, correspond with the documents in '/docs/');

(4)  Inconsistent formats, not in the github repository, but in the build
     directory (e.g., three different formats for README files);[1]

(5)  The conflation of "core" developer documents ("Developer Documentation")
     with HLL-developer documents ("User Documentation") (e.g., '/docs/html/index.html')

(6)  The lack of manpages (or Pods) for the installable binaries (e.g.,
     parrot);

(7)  The absence (or, if there is any, I haven't discovered it yet) of any
     documentation about Parrot's libraries (e.g., how does a HLL-developer
     make an OS system call?);

(8)  Far too much "institutionalized or assumed knowledge -- by which I mean
     knowledge gleaned over many months or years of working on Parrot -- or
     is penned directly into the documents (e.g., not every HLL-developer is
     familiar with vtables, especially Parrot's highly esoteric implementation
     of vtables);[2]

(9)  An inability to locate and to search quickly the archives (e.g.,
     #parrot-dev or #irc.parrot.org);

(10) An inability to locate specific items of information quickly (e.g., where
     do you look to take a number to the power of e in Parrot?);

(11) An inability for a HLL-developer to know when to make something a PMC, a
     dynpmc or a "specialized PMC data type" (e.g., an Hash Array Mapped Trie
     (HAMT) or a Regexp implementation[3]).

These are just some the more obvious problems with Parrot's documentation, there
are other, more subtle issues (e.g., nonconforming documentation in the source
code; mostly correct, but slightly misleading content in several documents,
etc.).  The net effect of which is a not insignificant barrier to all but the
most zealous of developers.[4]

Given this and given the Parrot Community's desire to provide a solution set
to the above, I propose the following:

(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.

(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.

(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]    

     (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]

(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]

(7)  I will, after receiving the necessary direction, set up the documentation
repo no later than the end of this weekend, i.e., this Sunday, November 6,
2011.

(8)  I will ask bubaflub to start a review of source code documentation
compliance.

(9)  I will attend to other, less pressing, but nonetheless important issues
as time permits (e.g., locating old, documents, videos, presentations, and
other links for an archive; tagging Wikibooks; etc.).

     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?

     	   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? 

The above nine items reflect, more-or-less, my present thinking on the
matter.  This said, I am not wedded to any specific item.  (Though, I do think
Parrot's documentation needs to be separated out along similar lines as the
above.)  And I am very open to anyone's suggestions on how best to proceed.

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!

Regards,

Alvis

--------------------
[*]  I would like first to thank everyone who took the time to provide me with
their thoughts and insights, most particularly, Christoph Otto, the
"Architect," Jonathan "Duke" Leto, the "Community Manager," Brian Gernhardt,
"core" developer, and Moritz Lenz, "Perl6/Parrot Liaison."  

     Note: This is a tentative plan only.  That is, it is an effort, a single
step, in a forward direction.  I am very open and very willing to any ideas,
suggestions or corrections on how best to improve Parrot's documentation.

[1]  I understand there is something of a consensus of opinion about READMEs,
which says, "No-one reads README files."  (Perhaps, I am the exception, but I
don't really think so.)  I do read READMEs, and I *expect* them to comport
with certain industry standards-and-practices.  Or, if they don't, I expect a
good explanation or rationale as to why they do not.  Moreover, *my*
view/experience/prejudice is such that, if a project fails to get something as
trivial as its READMEs correct, it says something about the project and the
project's commitment to its documentation.

[2]  For example, there are very highly skilled developers on other platforms,
e.g., the JVM, who do not necessarily grok Parrot's vtable implementation in
"all its glory."  Not only that, Parrot's implementation runs a'foul of the
reasonable expectations of those who have worked with vtables in other
languages.

     Please note: I am not saying this is either good or bad; I am only
     saying that some pointers, i.e., references, to other documents or,
     alternatively, a more detailed explanation of the hows and the whys of
     Parrot's implementation would, I think, go a long way to breaking down
     barriers to future HLL-development on Parrot.

[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.)

[4]  By which I mean those who have, largely, in one-way or the other, come
out of the Perl Community and, consequently, perceive the merit, even the
virtue, of Parrot's success.  The delivery of a "real" write once, run
anywhere platform for dynamic languages. 

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

[6]  As everyone will note, the writing of these manuals will demand a serious
and substantial commitment of time and of effort.  To this end, I will commit
to seeing these manuals through to their completion.

     Note: Unless, of course, I die, which is always a possibility.  Parrot's
     bus-factor is, imo, too high.

[7]  When I say, "I will write ...," I will, but I'd be very pleased to let
anyone, who wants to, take over any of these, "I will write"s. :-)

[8]  This said, I suck at html.  I've written my fair share of web-pages, but
I decidedly do not enjoy it.  Still, I would like to "come up with" and present
an alternative layout.  I will also "come up with" an alternative logo,
something a'kin to cotto's suggestion, unless I hear vehement opposition to
the contrary.  (I just happen to like zenny-type minimalism. :-)

     Please note: None of this is (or will be) set in stone.  It is just
     another bit of experimental code.