[Cuis-dev] Documenting Cuis

[Philip Bernhart]

Hi Hilaire,

Hilaire Fernandes via Cuis-dev <cuis-dev at lists.cuis.st> writes:
> What about more structured documentation, like a book, (with content 
> related to LeaningCuis and CodeExample). We could each other insert our 
> knowledge in documentation notes into it. I think I could spend 30 
> min/day on such a project.

I have a strong opinion about that.

And this is, that it's a waste of community time to produce "books".
It reminds me on the way other open Smalltalk systems are "documented",
which is exactly like this, which was and is unhelpful to newcomers.

I found any "book" which was written for other open Smalltalk systems,
explaining nothing with a lot of words.

Starting any such book project within the community,
would mean for me that really bad documentation practices from
other projects are brought to Cuis.

Any well written plain text README, collection of Cuis snippets
or design documents to explain the big picture did
for me more than reading any "book" in explaining Cuis to me.

This is also the way of how other open source projects do their
documentation, small simple and up-to-date.

What I don't want to say is, that IF some people want to write
"the ultimate reference" to Cuis (like an O'Reilly Book) there
is nothing to say about that, but not for any "technology" within
the project. Or basing the main documentation of system on that.
For me using books as documentation is a figleaf for general
bad documentation practices.

Any documentation of Cuis should be small maintainable .txt files,
further updated "Terse Guides to X" or any in Cuis based documentation
systems (Erudite?). Such simple efforts are way better invested time
than some unsung heros who write books.

That is my strong opinion regarding book-based documentation and which
is fueled through my frustration with the book-based documentation of
other open Smalltalk systems.


Have a nice sunday,
Philip