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!
Project Proposal.pdf (5K) Download Attachment |
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 There are actually two parts to this: 1) Indexing by Google is a must. The first hit on the above searches leads you directly to the right places. 2) The styles of the documentation is quite different. The Python docs provide context, giving a good overview. The php docs are purely reference docs but have a huge amount of user-contributed code snippets. Both are valuable styles of documentation. * 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. * 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. 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! > > > > |
In reply to this post by Casey Ransberger-2
Am 21.04.2010 07:18, schrieb Casey Ransberger:
> Anyway, I'm dying to hear what people think! Nothing to die for... The PDF comes up completely blank with the Ubuntu PDF displayer (evince). Looks like evince isn't able to handle the embedded type1 font, strange. As always with attached documents in mail, please consider twice whether what you want to say can't be said in simple words within an e-mail. I realize that sending PDFs is much friendlier than using some document format invented by you-know-who. I could select the invisible text and copy it into a workspace, so the textual contents were readable. Overall, I think the direction sounds nice, but I can't say whether it will work - that depends on getting a critical mass of Squeakers into the boat. Cheers, Hans-Martin |
In reply to this post by Andreas.Raab
On Tue, Apr 20, 2010 at 10:43 PM, Andreas Raab <[hidden email]> wrote: Excellent ideas! I'll make a couple of assorted notes which you are completely free to ignore :-) 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. 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, |
On 4/20/2010 11:23 PM, Casey Ransberger wrote:
> * 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. help pages simply via: HelpOnHelp edit: #introduction. This uses the trick that I mentioned above. You can edit text just like you usually would with all Squeaky goodness like emphasis, doIts, printIts etc. When done, simply accept and the method gets compiled. Extra bonus: Changing the window label also changes the topic title :-) Cheers, - Andreas CustomHelpEditing.st (1K) Download Attachment |
In reply to this post by Andreas.Raab
Seeing this, i was reminded of
http://soek.goodies.st/ So Long, -Tobias Am 2010-04-21 um 07:43 schrieb Andreas Raab: > * 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 > There are actually two parts to this: 1) Indexing by Google is a must. The first hit on the above searches leads you directly to the right places. 2) The styles of the documentation is quite different. The Python docs provide context, giving a good overview. The php docs are purely reference docs but have a huge amount of user-contributed code snippets. Both are valuable styles of documentation. |
That's pretty darned nice. Do you happen to know what the stack looks like there? Is it Squeak? Pharo? VW? I'm going to try to figure out who's site that is and make contact in the next couple of days.
On Wed, Apr 21, 2010 at 12:20 AM, Tobias Pape <[hidden email]> wrote: Seeing this, i was reminded of |
On 4/21/2010 12:38 AM, Casey Ransberger wrote:
> That's pretty darned nice. Do you happen to know what the stack looks > like there? Is it Squeak? Pharo? VW? I'm going to try to figure out > who's site that is and make contact in the next couple of days. http://philemonworks.wordpress.com/2009/11/13/soek-goodies-st-exploring-open-source-smalltalk-libraries/ Tags: s3, seaside, Smalltalk, soek, WebVelocity |
In reply to this post by Casey Ransberger-2
Hi Casey,
that's a nice proposal, thanks. I basically agree with the ideas and preliminary agenda - details are missing, of course, but that's fine. First of all, please fill me in about the "pink plane" idiom. I don't understand that. :-) -> "Audit and improve existing class comments, and compose or procure class comments for classes which have none" Sure, that needs to be done - I have one concern, though. How is it going to be packaged? Class comment changes will have to be "released" in the form of Inbox or Trunk uploads right now, right? I don't think this is a very good thing. While documentation should always evolve along the code it is intended to document, it should not be necessary to update the *code* package when only the *documentation* changes. In my opinion, a packageable documentation format is very important. That also makes documentation kind of optional in an image - and production images could be shipped (or production software installed) without the documentation. I know I'm touching upon some pretty hard-wired things: class comments have, for a long time, been directly associated with classes. Can that be decoupled somehow? In a nutshell, it would be really cool if it was possible to work on documentation while the code in the image rests, and just pull in updated documentation as it becomes available. Best, Michael |
In reply to this post by Casey Ransberger-2
> * 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: > > http://www.ruby-doc.org/core/ As for embedded documentation, I would recommend to check Emacs (featuring tutorial, books, info pages, introspection and function doc strings all integrated together) and Factor (amazing browsers) http://docs.factorcode.org/ Stef |
Oh cool. Yes the Factor pages are hot. It's totally interactive, I love it. And yes, I use Emacs when I'm not using Squeak:)
On Apr 21, 2010, at 1:32 AM, Stéphane Rollandin <[hidden email]> wrote: >> * 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: >> >> http://www.ruby-doc.org/core/ > > As for embedded documentation, I would recommend to check Emacs (featuring tutorial, books, info pages, introspection and function doc strings all integrated together) and Factor (amazing browsers) > > http://docs.factorcode.org/ > > > Stef > > > > |
In reply to this post by Michael Haupt-3
On 4/21/10, Michael Haupt <[hidden email]> wrote:
> Hi Casey, > > that's a nice proposal, thanks. I basically agree with the ideas and > preliminary agenda - details are missing, of course, but that's fine. > > First of all, please fill me in about the "pink plane" idiom. I don't > understand that. :-) Yes, "pink plane" has a special meaning. I assume Casey want's to allude to it. However for the time being why not just talk about 'HelpSystem'. Personally I would like to see a focus on short term attainable goals. Hannes |
In reply to this post by Michael Haupt-3
On 21.04.2010, at 10:29, Michael Haupt wrote:
> > Class comment changes will have to be "released" in the form of Inbox > or Trunk uploads right now, right? I don't think this is a very good > thing. While documentation should always evolve along the code it is > intended to document, it should not be necessary to update the *code* > package when only the *documentation* changes. IMHO the code is exactly where the documentation belongs. Sure, make external editors and even formats or databases or whatever if that is more convenient. But the authoritative version should be the one in the image. It's not official unless committed. > In my opinion, a packageable documentation format is very important. > That also makes documentation kind of optional in an image - and > production images could be shipped (or production software installed) > without the documentation. I agree that the documentation should be removable from the image. But in production you wouldn't ship the sources anyway. Comments are only in the source files, not the image. And if methods are used to store documentation literally, those could be removed when deploying. But the primary documentation should be internal. External documentation should be generated from the image, not the other way around. - Bert - |
Hi Bert,
On Wed, Apr 21, 2010 at 12:09 PM, Bert Freudenberg <[hidden email]> wrote: > IMHO the code is exactly where the documentation belongs. but that does not work for tutorials or anything that goes a few steps beyond plain class comments or single-method API-doc style documentation. "Documentation" is simply more than just that. > But the primary documentation should be internal. External documentation should be generated from the image, not the other way around. I agree wrt. API documentation, but I firmly believe that higher-level documentation is what many people would like to see. I'm extrapolating from my own point of view here, and anyone that don't see themselves represented by this are free to disagree. :-) Best, Michael |
In reply to this post by Michael Haupt-3
On 21.04.2010, at 10:29, Michael Haupt wrote:
> > First of all, please fill me in about the "pink plane" idiom. I don't > understand that. :-) It's an Alanism. Look at VPRI's logo :) Dan Ingalls applied the planes idea to Squeak: ======================= There are two strong, often opposed forces at work in the Squeak team. But, we have managed to keep it together long enough that it's probably adequate to articulate the two and you can guess at where equilibrium will take us. These were most recently articulated in Alan's allusion to Koestler's metaphor of progress in two orthogonal planes: a horizontal pink plane of incremental improvement, and a vertical blue plane of paradigm shift. The colors are Alan's. Pink plane forces involve making an ever-better Smalltalk-80 system that can serve a wide range of research and academic needs, while leveraging off the large body of ST-80 documentation, existing code archives, and synergy with high-performance commercial ST-80 systems. In this plane, Squeak's high level of compatibility with the ST-80 language (and even with the MVCdisplay architecture) is a plus, and current progress forces are aimed at a higher performing interpreter, with support for block closures, exception handling, as well as some answer to various needs for finalization. [...] Blue plane forces involve a very different graphics model, evolution of the language model, and hopefully an even simpler, yet more powerful language kernel. Each of these constitutes significant change, and is thus at odds with various entrenched interests. At the same time, each offers significant benefits. ======================= Read the full thing: http://wiki.squeak.org/squeak/158 To Alan himself, the two planes are way more profound: http://www.memestreams.net/users/akira/blogid4041444/ - Bert - |
In reply to this post by Michael Haupt-3
On 21.04.2010, at 12:27, Michael Haupt wrote:
> > Hi Bert, > > On Wed, Apr 21, 2010 at 12:09 PM, Bert Freudenberg <[hidden email]> wrote: >> IMHO the code is exactly where the documentation belongs. > > but that does not work for tutorials or anything that goes a few steps > beyond plain class comments or single-method API-doc style > documentation. "Documentation" is simply more than just that. Ah, you're right. You were talking about class comments though, not tutorials. >> But the primary documentation should be internal. External documentation should be generated from the image, not the other way around. > > I agree wrt. API documentation, but I firmly believe that higher-level > documentation is what many people would like to see. I'm extrapolating > from my own point of view here, and anyone that don't see themselves > represented by this are free to disagree. :-) We don't actually disagree after all :) It's just that the links people were excited about (Python, PHP, Ruby) were all of the API doc kind. And *that* needs to be generated from the source code IMHO. - Bert - |
In reply to this post by Bert Freudenberg
Hi Bert,
thanks. The Koestler reference made everything clear and understandable. The colour metaphor was really unfamiliar. :-) Best, Michael |
In reply to this post by Bert Freudenberg
Hi Bert,
On Wed, Apr 21, 2010 at 12:35 PM, Bert Freudenberg <[hidden email]> wrote: > Ah, you're right. You were talking about class comments though, not tutorials. when I talk about documentation, it envolves all flavours. :-) The start were class comments; correct. But I was thinking a bit ahead. Sorry for not making that more clear. Best, Michael |
In reply to this post by Bert Freudenberg
On Apr 21, 2010, at 12:30 PM, Bert Freudenberg wrote: > > > Read the full thing: http://wiki.squeak.org/squeak/158 > > To Alan himself, the two planes are way more profound: > http://www.memestreams.net/users/akira/blogid4041444/ In this article, there is a non-working link to swiki.squeakland.org. Do you know what used to be on that server? Rita > > - Bert - > > > > |
In reply to this post by Casey Ransberger-2
Great excellent ideas & a very sensible proposal.
I'll support such initiative. Regards, CdAB signature.asc (269 bytes) Download Attachment |
Free forum by Nabble | Edit this page |