How do we document Squeak?  There are class comments (mostly), there are books and papers, but when we want to develop a detailed spec about something, what is the best way to do that?  



Requirements:



1. We need something that is easy enough for people to contribute.

2. Something that is easily maintained and modified

3. Something that is collaborative 

4. Something that is easily discoverable

5. Something that is not easily ignored

6. Something that can be tested! 

7. Something that can be versioned



There are existing options like our swiki and github readme, or github pages. 

There are third party tools available (https://readthedocs.org/) or (https://www.sphinx-doc.org/en/master/) which may be good but raise the bar for contributions. 

Maybe a loadable package that includes searchable documentation and tests. An Active Essay? (https://www.playfulinvention.com/emergence/active-essay.html).





I forgot to mention that this same Pillar/Git stuff can be served up via Seaside with a transform into xHTML too.

Now...getting Seaside->Git via a form will be problematic, but that is for another day.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20210717/ab53222f/attachment.html>