On Tue, Apr 20, 2010 at 10:43 PM, Andreas Raab andreas.raab@gmx.de wrote:
Excellent ideas! I'll make a couple of assorted notes which you are completely free to ignore :-)
- The most helpful documentation I've used in recent years is this: http://www.google.com/search?q=python+tuple http://www.google.com/search?q=php+explode
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:
- Note the influence of the ST-80 class browser.
- 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.
Indexing by Google is a must.
Yes. For a time my whole life was about being indexed by Google, when I was at WhitePages. I know this all too well.
- 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.
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.
* 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.
I think in this phase it's more important to get a process going than to try to perfect the tools.
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.
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.
Cheers,
- Andreas
On 4/20/2010 10:18 PM, Casey Ransberger wrote:
Please find the attached proposal. In a workspace, do
self braceFor: #theHorror.
Seriously, though, I decided to go full-bore with the crazy ideas here. I would very much appreciate feedback of the constructively critical variety. If people really hate these ideas, I can go back to the drawing board, and come back with something folks can get behind.
To be clear: I'd rather not do it all by myself, so I will be receptive to what you have to say about it.
I am, myself, somewhat concerned that I may have erred a bit far on the side of tools; OTOH, I suspect that part of the reason mine was the only hand that went up when volunteers were called upon for the 4.0 release may have been: it was not a technically sexy release, and ours is a community of engineers. So maybe the tool ideas will go over well and get people engaged, I don't know.
Anyway, I'm dying to hear what people think!