[squeak-dev] Documenting the system

gettimothy gettimothy at zoho.com
Sat Jul 17 18:04:18 UTC 2021


Hi Ron



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).



How do we, as a community, want to do docs?



Thanks,



Ron Teitelbaum









While I am currently very busy with other things, I will be returning to  work on this problem.



Pharo has a git based thing named  Pillar which is written in a variant of Markdown. This covers 1,2,3,4 and 7 in your post.



As Tim remarked, the HelpBrowser is fundamental to squeak also Monticello is fundamental to squeak.



So, my idea is to "round robin" the Pillar git stuff into Help browser and from there it can be put into monticello.



Also the monticello to help browser to git can be accomplished in the reverse.



My plan it to use the XTreams Parsing and develop a PEG  to handle the git to HelpBrowser conversion.



I have a major hurdle in my current XTreams Parsing project to overcome--this is several months out before I turn to this project.



Another benefit imho is that I can use EMACS and the abundant editing tools available specifically for editing books and such; I find that composing in the HelpBrowser is a chore.





I have another idle project in mind where I make documentation available via the workspace with a framework I call "Doc" that provides "all" available documentation on a query.

However, I think the "round robin/Pillar" part needs to be tackled first.


cheers,



tty
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.squeakfoundation.org/pipermail/squeak-dev/attachments/20210717/c7b7fa73/attachment.html>


More information about the Squeak-dev mailing list