Hi Angel, and sorry about the late reply. Inline, and I've cut it short to the points I've responded to.<br><br><div class="gmail_quote">On Sat, Jan 5, 2013 at 4:44 AM, Angel Java Lopez <span dir="ltr"><<a href="mailto:ajlopez2000@gmail.com" target="_blank">ajlopez2000@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi people!<div><br></div><div>I'm the "non-smalltalk dev" in this list ;-)  And I want to say something.</div>
</blockquote><div><br></div><div>Heh;) My resume mostly says "Ruby" these days. It said "Perl" before that. I'm hoping to make it say "Smalltalk" or something more directly related than "Ruby."</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div>Yes, I know there is the "Smalltalk way" of doing many things... </div></blockquote><div><br>
</div><div>Makes me think of: <a href="http://www.drdobbs.com/architecture-and-design/interview-with-alan-kay/240003442#">http://www.drdobbs.com/architecture-and-design/interview-with-alan-kay/240003442#</a></div><div><br>
</div><div>"<span style="font-family:Verdana,Arial,Helvetica,sans-serif;font-size:13px;background-color:rgb(249,250,252)">The most disastrous thing about programming — to pick one of the 10 most disastrous things about programming — there's a very popular movement based on pattern languages. When</span><a href="http://www.amazon.com/Pattern-Language-Buildings-Construction-Environmental/dp/0195019199/?tag=drdos-20" style="color:rgb(0,59,176);font-family:Verdana,Arial,Helvetica,sans-serif;font-size:13px;background-color:rgb(249,250,252)">Christopher Alexander</a><span style="font-family:Verdana,Arial,Helvetica,sans-serif;font-size:13px;background-color:rgb(249,250,252)"> first did that in architecture, he was looking at 2,000 years of ways that humans have made themselves comfortable. So there was actually something to it, because he was dealing with a genome that hasn't changed that much. I think he got a few hundred valuable patterns out of it. But the bug in trying to do that in computing is the assumption that we know anything at all about programming. So extracting patterns from today's programming practices ennobles them in a way they don't deserve. It actually gives them more cachet."</span></div>
<div><span style="font-family:Verdana,Arial,Helvetica,sans-serif;font-size:13px;background-color:rgb(249,250,252)"><br></span></div><div>What he said.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div>but... in other technologies, no help system is practically used (since last decade? more?). The flow is:</div>
<div><br></div><div>- Google search</div><div>- Giving post resulst, or stack overflow question, answers</div></blockquote><div><br></div><div>You left a piece out. Most of what you're searching for on Google after your first tutorial or two in most of these systems is API documentation. This is usually automatically extracted from the code (method/function signatures) and the comments in the code (so-called "documentation comments.") Most of the time this stuff can be rendered directly in several formats, e.g., text, html, markdown, etc, and more often than not, the documentation is generated and updated constantly by a continuous integration server.</div>
<div><br></div><div>Regardless, an advantage of doing it this way is that the code and the docs are related not by release version, but by *checkin,* which is nice -- even if most of the time no one documents anything, you want to make it painless when they do, so you just change the doc comment when you change what the code does and check it in.</div>
<div> </div><div>I wish I could find the email in question, but after talking about HelpSystem with Andreas for a bit and suggesting that we use it to capture our docs in the MC update stream, he sent me what amounted to a five-ish line patch which allowed you to change the content of the help and then accept (cmd/alt/ctrl-s, depending on OS) and it would dirty the Monticello package by storing the text of the help content in a method, thus causing the change to be easy to commit just like anything else. Unfortunately, I don't think it got integrated in the trunk, and I don't know why. Might just have found the cutting room floor.</div>
<div><br></div><div><a href="http://en.wikipedia.org/wiki/Cutting_room_floor">http://en.wikipedia.org/wiki/Cutting_room_floor</a></div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div>For samples, if the project is hosted in GitHub, usually there is a samples folder in the project. (well, I'm very proud of my samples in CobolScript</div>
<div><a href="https://github.com/ajlopez/CobolScript/tree/master/samples" target="_blank">https://github.com/ajlopez/CobolScript/tree/master/samples</a></div><div>;-)</div></blockquote><div><br></div><div>One of the things I wanted to do with HelpSystem was give it export formats, most importantly text and html. Text is trivial and html isn't hard to do. I've had other priorities though, so I haven't gotten it done. I'd much rather see <a href="http://docs.cuis.org">docs.cuis.org</a> than just a text file on GitHub.</div>
<div><br></div><div>Oh! And I forgot to mention: HelpSystem automatically extracts method signatures, and treats the first comment in every method as a doc comment (which actually works out pretty well, as it's a common stylistic affectation to document a method at the top.) So in most respects, other than the missing export feature, it's really a lot *more* like the way other systems do it. Also, it's only a couple of years old; if there's a "Smalltalk Way" it's got to be at least some ten to twenty years older than HelpSystem!</div>
<div><br></div><div>:D</div><div><br></div><div><snip /></div><div><br></div></div>-- <br>Casey Ransberger