OK, let's start on the first section (calling them "Sections", not
"Chapters"). As our first experiment, we will assume a treelike style
(section 1 --> 1.1, 1.2, 1.2.1, etc.); look at
http://www.mysql.com/documentation/ for an example of a good, detailed
documentation tree.
So let's go depth-first into a single section, and see what we learn.
--- SECTION 1 ---
SCOPE: Language Primitives. Everything in the language that needs to
be explained _before_ statements and operators are explained (i.e. A2 +
any overlooked information). At minimum:
-- how to declare and use variables
-- how to represent literal string and numeric values
-- how to work with strings and numbers
-- how to work with arrays, hashes, and references
-- an introduction to all perl6 builtin types
-- explanations of typecasting, context, scope
The following tasks may take place in parallel:
TASK 1a:
Produce a _complete_ outline of all necessary documentation for Section
1, including the topics introduced and the order in which those topics
are represented.
TASK 1b:
Determine the presentation of the material, i.e. come up with a strawman
design for how the material will look in each of these cases:
-- as online documentation
-- as manpages
-- in other (printable) forms
-- as executable test cases
TASK 1c:
Determine a schema describing the fields/elements of the documentation,
in order for the docs to be databased & later sliced in a variety of
ways (beginner manual, advanced specs, test cases, etc.) Input and/or
output requirements are, at minimum:
-- as XML
-- as HTML
-- as manpage (*roff)
-- as PDF
-- as LaTex
-- as POD
-- as executable test cases
Note that POD consists of formatting directives, not schema information,
and so cannot represent the information in a form sufficient for full
slicing. At this point it would therefore appear that XML is the most
obvious authoring option.
TASK 1d:
Determine how perl6-internals would best like to receive test cases
associated with this documentation, and what mechanism we will use to
produce those tests.
---
If you wish to assist in any of these tasks, please declare your intent
to do so on this list, then just have at it, posting your proposals here
ASAP. We've already informally started task 1a, for example.
Comments welcome.
MikeL
