<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta content="text/html;charset=UTF-8" http-equiv="Content-Type"></head><body ><div style="font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 10pt;"><div>Hi Ron<br></div><blockquote style="border: 1px solid rgb(204, 204, 204); padding: 7px; background-color: rgb(245, 245, 245);"><div><div><br></div><div dir="ltr"><div class="x_-17270385gmail_default" style="font-size :  small;">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?  <br></div><div class="x_-17270385gmail_default" style="font-size :  small;"><br></div><div class="x_-17270385gmail_default" style="font-size :  small;">Requirements:<br></div><div class="x_-17270385gmail_default" style="font-size :  small;"><br></div><div class="x_-17270385gmail_default" style="font-size :  small;">1. We need something that is easy enough for people to contribute.<br></div><div class="x_-17270385gmail_default" style="font-size :  small;">2. Something that is easily maintained and modified<br></div><div class="x_-17270385gmail_default" style="font-size :  small;">3. Something that is collaborative <br></div><div class="x_-17270385gmail_default" style="font-size :  small;">4. Something that is easily discoverable<br></div><div class="x_-17270385gmail_default" style="font-size :  small;">5. Something that is not easily ignored<br></div><div class="x_-17270385gmail_default" style="font-size :  small;">6. Something that can be tested! <br></div><div class="x_-17270385gmail_default" style="font-size :  small;">7. Something that can be versioned<br></div><div class="x_-17270385gmail_default" style="font-size :  small;"><br></div><div class="x_-17270385gmail_default" style="font-size :  small;">There are existing options like our swiki and github readme, or github pages. <br></div><div class="x_-17270385gmail_default" style="font-size :  small;">There are third party tools available (<a href="https://readthedocs.org/" target="_blank">https://readthedocs.org/</a>) or (<a href="https://www.sphinx-doc.org/en/master/" target="_blank">https://www.sphinx-doc.org/en/master/</a>) which may be good but raise the bar for contributions. <br></div><div class="x_-17270385gmail_default" style="font-size :  small;">Maybe a loadable package that includes searchable documentation and tests. An Active Essay? (<a href="https://www.playfulinvention.com/emergence/active-essay.html" target="_blank">https://www.playfulinvention.com/emergence/active-essay.html</a>).<br></div><div class="x_-17270385gmail_default" style="font-size :  small;"><br></div><div class="x_-17270385gmail_default" style="font-size :  small;">How do we, as a community, want to do docs?<br></div><div class="x_-17270385gmail_default" style="font-size :  small;"><br></div><div class="x_-17270385gmail_default" style="font-size :  small;">Thanks,<br></div><div class="x_-17270385gmail_default" style="font-size :  small;"><div><br></div><div>Ron Teitelbaum<br></div></div></div></div></blockquote><div><br></div><div><br></div><div>While I am currently very busy with other things, I will be returning to  work on this problem.<br></div><div><br></div><div>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.<br></div><div><br></div><div>As Tim remarked, the HelpBrowser is fundamental to squeak also Monticello is fundamental to squeak.<br></div><div><br></div><div>So, my idea is to "round robin" the Pillar git stuff into Help browser and from there it can be put into monticello.<br></div><div><br></div><div>Also the monticello to help browser to git can be accomplished in the reverse.<br></div><div><br></div><div>My plan it to use the XTreams Parsing and develop a PEG  to handle the git to HelpBrowser conversion.<br></div><div><br></div><div>I have a major hurdle in my current XTreams Parsing project to overcome--this is several months out before I turn to this project.<br></div><div><div dir="ltr"><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default">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.<br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default">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.<br></div><div style="font-size :  small;" class="x_-17270385gmail_default">However, I think the "round robin/Pillar" part needs to be tackled first.</div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default">cheers,<br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default">tty</div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div><div style="font-size :  small;" class="x_-17270385gmail_default"><br></div></div><br></div><div><br></div></div><br></body></html>