Carl observed: > Partly that is because documentation isn't at the forefront of things > that need to be implemented for Perl 6 to be useful, so it's kind of > lagging behind the rest. > > Partly it's because Damian is the "owner" of that synopsis, and he > practices a kind of "drive-by-updating" to it. As a case in point of > this latter effect, the extensive changes made by Damian in August > *still* haven't hit the Pugs repo.
The latter is entirely true but, fortunately, also very easily remedied. I hereby disclaim all present and future "ownership" of S26. :-) By all means put the latest update on the repo (or maybe remove S26 entirely), and start redesigning it collaboratively. Please note that I am not in any way upset, angry, petulant, or otherwise disaffected. I only want the very best for every aspect of Perl 6. If the experience of respected and active developers suggests that Pod 6 isn't a step in the right direction, I can only feel disappointed in myself, apologize for my failure, and gratefully turn the task over to those with better ideas and more time and energy to devote to the problem. As regards Pod vs Pandoc (which is pretty clearly the leading contender of the structured text notations), I do think Pod has some decided advantages. For example, I feel it's better to have four basic metasyntaxes (X<>, =IDENT, :OPTION, #=) and most with identifier-based labels, than to have over two dozen (plus embedded HTML and TeX) all with symbolic labels. I guess I feel that Pandoc/Markdown/ReST/etc. are optimized for writing documentation "source", whereas Pod is optimized for reading documentation "source". I'm not sorry I aimed for the latter, whatever the deficiencies in the result. Carl also suggested: > I think that the future of S26 is very much dependent on whether it'll > be able to respond to the needs of Perl 6 developers. Right now it > doesn't respond to much of anything. Outwardly this is self-evidently true. One need only look at the (lack of) commit log for S26. :-( Inwardly, something else entirely is happening. A design(er) can only respond effectively when subjected to a clear net force pushing or pulling in some well-defined direction. The redesign of Pod has been subject to an enormous number of such forces. Unfortunately they push and pull it in every possible mutually contradictory direction, thereby producing very little overall impetus. So I would encourage those of you who are going to collectively take over the shepherding of this synopsis to go back through the p6l archives and review the many many posts commenting on and requesting features for Perl 6 documentation. In particular, please look carefully at the very different needs of those who document OO code, procedural code, frameworks, modules, applications, design documents, presentations, and Perl itself. You will find that many of these contributors ignore, discount, or actively disparage the needs of their fellow users. For example, in this very thead: > I'm not writing a book, I'm writing code. And if I was writing a book, > I wouldn't be dumb enough to write it in POD. Yet what is the Perl documentation itself but a series of book chapters? And surely that documentation is the largest single use of Pod anywhere? Should we not write Perl's own documentation in Perl's own documentation notation? Should we really discourage the use of standard headings to consistently mark the common components of these (and most other) Perl-related documents? I sincerely hope that the future community of designers of Perl 6 's documentation format will find a way to honour and support the very different needs of *all* the creators and users of Perl, not just the needs of the most prominent, or the needs of the most experienced, or the needs of the most loquacious. I have always thought that was the *real* challenge of post-modern language design. Damian
