[Cuis-dev] Documenting Cuis

[Dan Norton]

+1

Any suggestions for improving Learning Cuis and Terse Guide are
welcomed.

 - Dan

On Sun, 05 Jul 2020 20:41:14 +0200
Philip Bernhart via Cuis-dev <cuis-dev at lists.cuis.st> wrote:

> 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