<br><br><div class="gmail_quote">On Tue, Apr 20, 2010 at 10:43 PM, Andreas Raab <span dir="ltr"><<a href="mailto:andreas.raab@gmx.de">andreas.raab@gmx.de</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
Excellent ideas! I'll make a couple of assorted notes which you are completely free to ignore :-)<br>
<br>
* The most helpful documentation I've used in recent years is this:<br>
<a href="http://www.google.com/search?q=python+tuple" target="_blank">http://www.google.com/search?q=python+tuple</a><br>
<a href="http://www.google.com/search?q=php+explode" target="_blank">http://www.google.com/search?q=php+explode</a></blockquote><div><br></div><div>Good stuff. I really like the feel of the Python version. They have great documentation in general. While we're looking at other web-based documentation frameworks, you must check out:</div>
<div><br></div><div><a href="http://www.ruby-doc.org/core/">http://www.ruby-doc.org/core/</a></div><div><br></div><div> - Note the influence of the ST-80 class browser.</div><div><br></div><div> - Scroll the middle pane, choose Array, click on the title of a method, and note that the implementation (probably in C) pops up in a new window. This is utterly primitive compared to what we can do, and still kind of cool.</div>
<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> Indexing by Google is a must. </blockquote><div><br></div><div>Yes. For a time my whole life was about being indexed by Google, when I was at WhitePages. I know this all too well.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
* Try to favor something that makes it easy for people to contribute visibly. I.e., updating a wiki site is not a visible contribution in our community. I'd rather see commit comments for the documentation so that the community is aware of new content and who contributes it.</blockquote>
<div><br></div><div>100% agreement. There are actually a number of reasons why it would be neat to harvest documentation with Monticello. Above all, it lets us keep linkage between documentation and the code that it describes. It also gets versioned. Maybe merging will prove useful. Visibility is also way cool. As I mentioned in my reply to Michael, we can also have e.g., an option to toggle between stable and nightly API docs right in the web browser, and use MC to pull docs straight to the server.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;"> </blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
* Shoot for a concrete near-term achievable goal, for example: Combining HelpSystem with the workspace hack that I used for the release workspaces (i.e., just compile the text as a method) and then just allow people to start writing things.<br>
<br>
I think in this phase it's more important to get a process going than to try to perfect the tools.<br></blockquote><div><br></div><div>Totally; what's funny is, I wasn't aware of HelpSystem until today (I seem to have missed the previous thread about it) and was expecting to have to build that part myself. My plan was to just send things #storeString and stick them in methods, and see how far that took me. I will dig through my files to revisit the workspace hack.</div>
<div><br></div><div>As I write this I've sent #storeString to a HelpTopic automatically generated from Integer and it looks as though it worked and performed acceptably. My gut say this is going to work.</div><div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
Cheers,<br><font color="#888888">
- Andreas</font><div><div></div><div class="h5"><br>
<br>
On 4/20/2010 10:18 PM, Casey Ransberger wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Please find the attached proposal. In a workspace, do<br>
<br>
self braceFor: #theHorror.<br>
<br>
Seriously, though, I decided to go full-bore with the crazy ideas here.<br>
I would very much appreciate feedback of the constructively critical<br>
variety. If people really hate these ideas, I can go back to the drawing<br>
board, and come back with something folks can get behind.<br>
<br>
To be clear: I'd rather not do it all by myself, so I will be receptive<br>
to what you have to say about it.<br>
<br>
I am, myself, somewhat concerned that I may have erred a bit far on the<br>
side of tools; OTOH, I suspect that part of the reason mine was the only<br>
hand that went up when volunteers were called upon for the 4.0 release<br>
may have been: it was not a technically sexy release, and ours is a<br>
community of engineers. So maybe the tool ideas will go over well and<br>
get people engaged, I don't know.<br>
<br>
Anyway, I'm dying to hear what people think!<br>
<br>
<br>
<br>
<br>
</blockquote>
<br>
<br>
</div></div></blockquote></div><br>