Parrot's Documentation set

[Alvis Yardley]

Hello All:

"By the the power of Grey ...."  No, wait ..., that's a line from the 
Green Lantern, which I just recently re-watched. :-)

Anyway, the Parrot Community Manager, Jonathan "Duke" Leto, has 
"blessed" me to shepherd the Parrot Community's effort to review, to 
revise, and, where appropriate, to revision Parrot's Documentation set.  
Given this rather broadly stated goal,[1] I am asking something equally 
broad of the Parrot Community:  Please, anyone and everyone, who either 
(1) wants to contribute to this endeavor or (2) simply has an opinion 
about the present condition of Parrot documentation,[2] take some time 
and offer us your opinions and your ideas on how best to, as Christoph 
Otto recently wrote, "make our docs shine."  In short, please provide us 
with your "critical assessments"[3] and "aspirational directions"[4] for 
the future of Parrot's Documentation set.

Examples of agenda items include, but are /not/ limited to,

(1) An overhaul of the parrot.org website;[5]

(2) How best to organize the documentation set;[6]

(3) Where best to house our documentation set;[7]

(4) The form in which to store the documentation, /e.g.,/ plain text, 
pod, markdown, etc.; and

(5) Whether or not to make concerted efforts to locate and to identify 
out-dated, but still valuable, documents about Parrot, /e.g.,/ the PIR 
Guide (and related) *.pds, Allison Randall's video presentations, etc., 
and properly archive them with something like, a **WARNING: THESE 
DOCUMENTS ARE OUT OF DATE** tag.

This list is neither inclusive nor extensive; it is merely indicative.  
For example, I have not even begun to address issues touching on the 
various "kinds" of documentation presently in Parrot, /e.g.,/ plain text 
README versus README.pod versus README.md[8] or tests to ensure 
conformity and compliance with pdd07_codingstd.pod or etc....

So, please, share your ideas and suggestions with us on how best to make 
Parrot's Documentation set shine.  It needs your love! :-)

Thank you.

Alvis

P.S.   Just to be clear: At this point in the game, I am /seriously/ 
seeking any and all help and direction from anyone and everyone within 
(and, to be honest, without) the Parrot Community.

P.S.S. Though I prefer to keep all discussion and, certainly, all 
decision points on-list, please feel free to contact me off-list if you 
prefer.

----------
[1]  To be fair, those are /my/ words, not Duke's.

[2]  Just to anticipate somewhat: Something more than, "it sucks," would 
be helpful. :-)

[3]  For example, executing a 'make html' /in/ '/docs' results in a (I 
would argue, "non-experimental") documentation set which, significantly 
-- and silently -- /diverge/s from the docs /in/ '/docs'.  Moreover, no 
where is this divergence (or the necessity of working, /not/ from the 
Pod in '/docs', but from the make-generated html documents instead) 
indicated.  A consequence of which is, a new HLL-developer (for example, 
me) who /prefers/ to work with Pod, rather than html, spends several 
weeks reading from and working with an out-of-date set of documents.

[4]  For example, implementing a help facility somewhat similar to, say, 
SWI-Prolog, where the user can invoke help the shell.  (Of course, 
ensuring support of partcl would help this along greatly.)

[5]  I have my own ideas about this, but I, for one, would like to hear 
everyone's opinion about (a) whether or not to, in fact, revise the 
parrot.org website or (b) if we do, what direction to take to accomplish 
the same.

[6]  For example, one obvious division quickly springs to mind: Clear, 
unambiguous, user-visible demarcation points among Parrot's feature set; 
its internals; its various APIs; its HLL developer support; its ....  
Another is a division between "core" documents and user-contributed wikis.

[7]  Where, imo, Github seems the most reasonable choice given Parrot, 
itself, is hosted on Github and tracking tickets are being migrated as 
well, but if others have a different view, I'm sure everyone would like 
to hear it.  (This sounds very loaded, doesn't it?  I sincerely do not 
mean it as a loaded question.)

[8]  I have read through /some/ (most I think) of the archived email, 
addressing this lack-of-uniformity issue, and I get it has been, in the 
past, the source of a "religious war"-type thing, but we, as a 
community, simply /must/ come to terms and resolve this outstanding 
issue.  It is /very/ disruptive and /very /confusing for a new 
developer.  He or she wonders, especially during the first week or two, 
while trying to figure things out, "Why this lack of uniformity in 
simple READMEs?"  And, then, he or she spends several, unproductive 
hours digging around only to find, "Oh, it's a "religious war" kind'a 
thing."  It's very unhelpful.

      Fwiw, my own view is, invoking the principle of least surprise 
seems the most sensible approach.  This said, there is, of course, 
nothing wrong with a community adopting approaches which differ from the 
approaches of other communities.  ;-)


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.parrot.org/pipermail/parrot-dev/attachments/20111026/244b25de/attachment.html>