On Wednesday, November 6, 2002, at 12:26 PM, Garrett Goebel wrote:
Yes! Someone gets it! The Apocalypses and Exegesis are not "formal" documentation, they're the initial, informal specs. The finished documentation won't look anything like them, right?Angel Faus wrote:So, while we all wait for Larry to wait the design, is there any reason not to start working in the documentation?
My problem with a wiki approach is that it tends to lead to lots of duplication of effort, with some sections entirely ignored, as well as a wide range of writing styles. I think a better approach is, indeed, for the community to help with documentation, but to do so in a more structured way. This is why I prefer a mailing list approach, with questions & answers posted, then documented, in a particular, fairly rigid order, where everyone is concentrating on the same excruciating details at once, then boom, it's done, move on. Right now we have the mailing list, but not the structure.Any chance of getting a wiki setup at:
Two notes:
1) The primary need right now is not documentation in itself, but the community process of *writing* the documentation. It is by methodically *finding* the holes in the specification that the specification will finally becomes complete enough to implement accurately.
2) Anyone involved in a community documentation effort must agree that ALL of it is open source or public domain, and _specifically_ that any members of the community who will be writing treeware (books) may use any of that text in their own efforts. This is a dealbreaker, for me: I have zero desire to squish commercial documentation efforts -- I think those people deserve 100% of that income.
On Wednesday, November 6, 2002, at 12:26 PM, Nicholas Clark wrote:
I see no reason why this doesn't also apply to specs vs regression tests.I confess I have worked that way myself, on some projects, but I fear we aren't capable of that yet. We still need to flesh out the "english" explanations of co-routines, superpositions, and other advanced features. I would rather define how it worked, and test to that, then test how it worked, and write up the english implications as we accidentally discover them.
So either we have the definitive docs that define all the details of the
language, or we have the regression tests that define all the details.
MikeL
