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. ;-)
_______________________________________________
http://lists.parrot.org/mailman/listinfo/parrot-dev
