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!
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!
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!
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.
Try this too: Load HelpSystem, file in the attached code. Then edit your 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
* 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+explodeGood 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:
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)
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 lecteur@zogotounga.net 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:
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)
Stef
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 Das.Linux@gmx.de wrote:
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.
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...
Tags: s3, seaside, Smalltalk, soek, WebVelocity
On Wednesday 21 April 2010 11:13:55 am Andreas Raab 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
While we are on the topic of helpful documents, I want to point out Qt's integrated documents at: http://qt.nokia.com/developer
It makes good use of hyperlinks and RSS to tie together API indices, reference, tutorials, blogs, video clips. e.g.
http://labs.trolltech.com/blogs/2010/04/09/the-future-continued
Subbu
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
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
On 4/21/10, Michael Haupt mhaupt@gmail.com 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
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 bert@freudenbergs.de 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
On 21.04.2010, at 12:27, Michael Haupt wrote:
Hi Bert,
On Wed, Apr 21, 2010 at 12:09 PM, Bert Freudenberg bert@freudenbergs.de 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 -
Hi Bert,
On Wed, Apr 21, 2010 at 12:35 PM, Bert Freudenberg bert@freudenbergs.de 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
One of the big advantages of SUnit and its ilk are that tests are "just code". They can be versioned, inspected, refactored, released, announced, etc just like code, because they are code.
So, I think it is great that you are trying to put documentation on the same level.
It looks to me like you are thinking of several tools here. One converts documentation into HTML. This might be a web site that just displays what is in the image, or it might be a tool that goes through the image and creates HTML, writing it out to the disk for display later.
Another is a way of including more tutorial-style documentation in the image, and you are thinking about HelpSystem, right?
I assume you would like the material in HelpSystem to be on the web, too.
-Ralph
On 4/21/10, Ralph Johnson johnson@cs.uiuc.edu wrote:
One of the big advantages of SUnit and its ilk are that tests are "just code". They can be versioned, inspected, refactored, released, announced, etc just like code, because they are code.
So, I think it is great that you are trying to put documentation on the same level.
Yes, that is actually what Andreas and Torsten are doing right now.
It looks to me like you are thinking of several tools here.
Yes.
One converts documentation into HTML. This might be a web site that just displays what is in the image, or it might be a tool that goes through the image and creates HTML, writing it out to the disk for display later.
Yes.
Another is a way of including more tutorial-style documentation in the image, and you are thinking about HelpSystem, right?
Yes.
I assume you would like the material in HelpSystem to be on the web, too.
Yes.
-Ralph
And we need an agreement on the kind of text format the 'original' of the documentation is stored in. The selection of a lightweight markup language http://lists.squeakfoundation.org/pipermail/squeak-dev/2010-April/149201.htm...
It is not so important which one as long as we use a common subset and have converters between the various approaches. Somebody suggested 'reStructuredText' http://docutils.sourceforge.net/rst.html
What is currently in use is plain text (Torsten B. / HelpSystem) and the Smalltalk text format (Andreas R. / Help menu)
--Hannes
On Apr 21, 2010, at 3:35 AM, Bert Freudenberg wrote:
On 21.04.2010, at 12:27, Michael Haupt wrote:
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.
Actually, the Python link that Andreas sent was to the Python Tutorial, which isn't of the "API doc kind". It's quite impressive.
Cheers, Josh
- Bert -
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 -
Hi Bert,
thanks. The Koestler reference made everything clear and understandable. The colour metaphor was really unfamiliar. :-)
Best,
Michael
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 -
Great excellent ideas & a very sensible proposal.
I'll support such initiative.
Regards,
CdAB
Hello Casey,
A short plan is the step in the right direction. I believe our community needs more sense of direction. I'd like to bring few things that seems to be missing in your proposal, for your consideration (and everyone else).
There is no inclusion of additional tools in order to make sure we have quality documentation. For example, why not having hunspell [1] integrated? A good spell checker will make a huge difference. I would also consider versioning documentation important since our wiki suffers from the lack of it (shall we learn from our past mistakes?).
[1] http://hunspell.sourceforge.net/
I would much more consider contribute on documentation provided editing and formatting tools are available, ability to include screenshots, and other goodies. I don't care about the internal format. I am a big fan of LaTeX and I don't use it anymore because editing softwares nowadays do it much faster and it's way easier. Faster and easier mean more contributions.
Your plan is overenthusiastic in my opinion. I don't think our community can undertake everything listed. It would be much better to look at what is the most needed in term of documentation and have people to focus on it. It will reduce the risks of failure. We can build around this documentation and slowly move on other parts. We need something usable for the largest segment of the community.
Squeak Documentation Team is all right for a name. Let's stick to simple. Simple usually works better. :P
Best regards, Ian.
One thing I didn't do, that I probably should have done, is to explicitly list what I think our priorities should be regarding documentation. As much as it pains me that we don't have a spell checker, for example, I'd put that waaay behind a cleanup effort for class comments; I'd put *all* tool work behind that.
I've thought a lot about how best to limit scope such that a documentation project can deliver quickly. For a first shot, I'd like to limit scope to what's in the image after one does 'Smalltalk unloadAllKnownPackages'. Of course we should have great documentation for everything that comes in a standard Squeak image, but knowing that our resources are limited, in a triage I would call out everything in a core image as priority-1, with the contents of a standard image as priority-2.
So here's my top three priorities (you may of course disagree:)
1. Get a process running around using HelpSystem. 2. A useful, current comment for every class. 3. Consider first method comments which show up in tools that can extract them.
On Fri, Apr 30, 2010 at 2:24 AM, Ian Trudel ian.trudel@gmail.com wrote:
Hello Casey,
A short plan is the step in the right direction. I believe our community needs more sense of direction. I'd like to bring few things that seems to be missing in your proposal, for your consideration (and everyone else).
There is no inclusion of additional tools in order to make sure we have quality documentation. For example, why not having hunspell [1] integrated? A good spell checker will make a huge difference. I would also consider versioning documentation important since our wiki suffers from the lack of it (shall we learn from our past mistakes?).
[1] http://hunspell.sourceforge.net/
I would much more consider contribute on documentation provided editing and formatting tools are available, ability to include screenshots, and other goodies. I don't care about the internal format. I am a big fan of LaTeX and I don't use it anymore because editing softwares nowadays do it much faster and it's way easier. Faster and easier mean more contributions.
Your plan is overenthusiastic in my opinion. I don't think our community can undertake everything listed. It would be much better to look at what is the most needed in term of documentation and have people to focus on it. It will reduce the risks of failure. We can build around this documentation and slowly move on other parts. We need something usable for the largest segment of the community.
Squeak Documentation Team is all right for a name. Let's stick to simple. Simple usually works better. :P
Best regards, Ian. -- http://mecenia.blogspot.com/
2010/4/30 Casey Ransberger casey.obrien.r@gmail.com:
One thing I didn't do, that I probably should have done, is to explicitly list what I think our priorities should be regarding documentation. As much as it pains me that we don't have a spell checker, for example, I'd put that waaay behind a cleanup effort for class comments; I'd put *all* tool work behind that.
I completely disagree on this one. I would concede that editing and formatting tools may not be as high priority as a spell checker. However, a spell checker should be mandatory. Many in our community are non-native English speakers.
Let's imagine there is a documentation frenzy without a spell checker. People contribute like crazy and we are on a roll. Great you say. Great it is. Then we realize that we have more documentation but with poor quality, it's hardly readable. We will be forced to rework all texts. It sounds like documenting twice the same system! :O
So here's my top three priorities (you may of course disagree:)
- Get a process running around using HelpSystem.
I believe in the HelpSystem. It needs some tweaking but it's a good system to begin with. A mechanism for content contribution and distribution, as you called it, should be put in place quickly. Trunk style. Perhaps even integrated to the trunk. It has to be available everywhere to ensure a good stream of contributions.
- A useful, current comment for every class.
This could be a good start. One of the thing that should be higher in priority than #3 is usage examples. It is sometimes time consuming to figure out how to properly use some classes.
- Consider first method comments which show up in tools that can extract
them.
Another suggestion: we should have something to tell us how much documentation coverage we have. This set an objective to our community: having 100% coverage.
Ian.
Ian, thanks. Comments inline.
On Fri, Apr 30, 2010 at 1:36 PM, Ian Trudel ian.trudel@gmail.com wrote:
2010/4/30 Casey Ransberger casey.obrien.r@gmail.com:
One thing I didn't do, that I probably should have done, is to explicitly list what I think our priorities should be regarding documentation. As
much
as it pains me that we don't have a spell checker, for example, I'd put
that
waaay behind a cleanup effort for class comments; I'd put *all* tool work behind that.
I completely disagree on this one. I would concede that editing and formatting tools may not be as high priority as a spell checker. However, a spell checker should be mandatory. Many in our community are non-native English speakers.
Let's imagine there is a documentation frenzy without a spell checker. People contribute like crazy and we are on a roll. Great you say. Great it is. Then we realize that we have more documentation but with poor quality, it's hardly readable. We will be forced to rework all texts. It sounds like documenting twice the same system! :O
Somehow I doubt we'll have a documentation-frenzy. That would be a momentous day in software history, and a great problem to have.
Okay, I would love to have a spell checker in Squeak. It would need to be:
- Easy to install. I'm thinking, MC package. Requiring a VM primitive would set the barrier for contribution too high IMHO. - It should be easily unloadable (many of us probably have no use for a spell checker in our images.)
I don't know of a spell checker implementation for Squeak. Is there one out there? If not, can you implement one and then get back to me right away? :P
So here's my top three priorities (you may of course disagree:)
- Get a process running around using HelpSystem.
I believe in the HelpSystem. It needs some tweaking but it's a good system to begin with. A mechanism for content contribution and distribution, as you called it, should be put in place quickly. Trunk style. Perhaps even integrated to the trunk. It has to be available everywhere to ensure a good stream of contributions.
Agreed. I just sent another message about this.
- A useful, current comment for every class.
This could be a good start. One of the thing that should be higher in priority than #3 is usage examples. It is sometimes time consuming to figure out how to properly use some classes.
I think examples raise the quality of class comments. Absolutely.
- Consider first method comments which show up in tools that can extract
them.
Another suggestion: we should have something to tell us how much documentation coverage we have. This set an objective to our community: having 100% coverage.
This is actually something that I thought about doing. I'd call it a strong nice-to-have. This one seems like it wouldn't be that hard to pull off, either.
Coverage is kind of a funny metric though. 100% coverage is great to have, but doesn't tell you anything about the quality of your coverage.
Ian.
Thanks for your feedback!
2010/4/30 Casey Ransberger casey.obrien.r@gmail.com:
Ian, thanks. Comments inline.
My pleasure, I like plans. :)
Somehow I doubt we'll have a documentation-frenzy. That would be a momentous day in software history, and a great problem to have.
That's not what your plan said. As I wrote, it's a bit overenthusiastic for a period of one year. My point was simply that a spellchecker is important and it will make a difference over time. We both agree on this. Fine. :)
Okay, I would love to have a spell checker in Squeak. It would need to be:
- Easy to install. I'm thinking, MC package. Requiring a VM primitive would
set the barrier for contribution too high IMHO.
- It should be easily unloadable (many of us probably have no use for a
spell checker in our images.)
The easiest approach would probably be to use an existing system, such as hunspell. It has been used with many systems (OO.o, Firefox, Opera) and many programming languages. There are probably all the compiled libraries needed to interface with. It comes with many dictionaries in various languages.
I don't know of a spell checker implementation for Squeak. Is there one out there? If not, can you implement one and then get back to me right away? :P
Neither do I know.
Agreed. I just sent another message about this.
Yes, great. :)
- Consider first method comments which show up in tools that can
extract them.
Another suggestion: we should have something to tell us how much documentation coverage we have. This set an objective to our community: having 100% coverage.
This is actually something that I thought about doing. I'd call it a strong nice-to-have. This one seems like it wouldn't be that hard to pull off, either. Coverage is kind of a funny metric though. 100% coverage is great to have, but doesn't tell you anything about the quality of your coverage.
You're correct about quality. My idea is to set an objective first and foremost. We could define basic requirements for comments. I see online help often have something to rate the help page they have been reading (“How useful this entry was?” 1 – Useless, 5 – Excellent). We could consider something along this line.
Ian.
Hi,
sorry for being late, but week-ends are for relaxing sometimes. :-)
Regarding spell checking and the upcoming documentation frenzy, I don't think poor spelling will be that much of a problem for two reasons. First, I don't believe that so many people speak and write such a poor English that it deserves utmost attention. Second, if the documentation process allows for trunk-like quick pushes to the repository, glitches and unclear formulations can be quickly mended by anyone interested in doing so.
Given that the number of people who are actually willing to commit to the documentation thingy can be expected to be low (yup, call me a pessimist), we can nevertheless expect high interest in good documentation in those who contribute. So - let's not worry about the spelling issues right now.
In a nutshell, I think that getting a possibly external spell checker to work in Squeak may be an interesting project, but it's not really of immediate help with regard to the documentation plans. (If the above observations are correct.)
Regarding quality of documentation (more precisely: of class comments), I would expect the best quality from those who know most about the classes in question. But will those people write the most? Not necessarily. So how about this: someone writes the documentation for a class and commits it, and the next thing is to ask those three people who had the most commits to that very class for their opinion on the documentation.
Best,
Michael
Hi Michael,
It is an unexpected comment from a German. My experience in the German market made it clear Germans demand high-quality writings — in German that is. The companies I have worked for were paying top dollars for near-perfect German writings, from advertisement to documentation.
The English market is more lax but I have seen its limits. Poor quality documentation turned against one software vendor I worked for few years ago. It did undermine sales and the broken English documentation made the top 3 most complains.
Squeak is a product that happens to be free-of-charge. I wrote that once. :)
My point is that we have more to gain to do it right from the ground up. The efforts required to interface with a spellchecker library is much less now than rewriting documentation later. I like your idea about asking code contributors for their opinion but it's difficult to get feedback from others in our community at the moment. Plus, barely few want to write documentation along their code. Nobody rewrite documentation. :O
What we will be writing will be stuck for years in our documentation system with little chances for update assuming that documentation gets some attention from a small part of our community (and no more). I am all about increasing our chances of success. :)
Question. Does HelpSystem support syntax highlight? It would be great to insert piece of codes properly formatted. In fact, if you guys look at my recent article on my blog, this is the kind of visual elements we might need to provide an appealing documentation.
Ian.
Hi Ian,
On Sun, May 2, 2010 at 2:37 PM, Ian Trudel ian.trudel@gmail.com wrote:
It is an unexpected comment from a German. My experience in the German market made it clear Germans demand high-quality writings — in German that is. The companies I have worked for were paying top dollars for near-perfect German writings, from advertisement to documentation.
see, that's what stereotypes are for: being reconsidered. :-)
I think it is much more important to get some documentation available. Polishing is always possible. There is no business contract involved here, and no $$$ lurking. At least not for me.
My point is that we have more to gain to do it right from the ground up. The efforts required to interface with a spellchecker library is much less now than rewriting documentation later. ...
Correct spelling alone doesn't make good quality, does it?
Best,
Michael
2010/5/2 Michael Haupt mhaupt@gmail.com:
Hi Ian,
Hi Michael,
On Sun, May 2, 2010 at 2:37 PM, Ian Trudel ian.trudel@gmail.com wrote:
It is an unexpected comment from a German. My experience in the German market made it clear Germans demand high-quality writings — in German that is. The companies I have worked for were paying top dollars for near-perfect German writings, from advertisement to documentation.
see, that's what stereotypes are for: being reconsidered. :-)
I see. Companies however collect demographic data and it makes sense to consider such feedback. The important is to make a decision in a knowledgeable manner. Spell checker could be entirely excluded but at least it would be a decision taken in knowledge of its advantages and disadvantages. :)
I think it is much more important to get some documentation available. Polishing is always possible. There is no business contract involved here, and no $$$ lurking. At least not for me.
Some documentation is already available: http://wiki.squeak.org/squeak
Polishing did not happen.
o_O
My point is that we have more to gain to do it right from the ground up. The efforts required to interface with a spellchecker library is much less now than rewriting documentation later. ...
Correct spelling alone doesn't make good quality, does it?
You're right. Every detail matters to make good quality. *grin*
Best,
Michael
Quality is something I take at heart and I usually refrain from releasing anything that does not match a minimum quality standard as far as open source contribution goes and I release commercial work only when it matches my highest quality standard. A spell checker is among the tools I use to write documentation, articles, etc. I will survive if it's not in our HelpSystem but I know it will become an additional hurdle to me. I will probably end up writing in OpenOffice and transfer back in Squeak. Painful.
Anyway, when are we getting HelpSystem integrated to the trunk again? We could be typing in there instead. :)))
Ian.
Hi Ian,
On Sun, May 2, 2010 at 3:21 PM, Ian Trudel ian.trudel@gmail.com wrote:
Some documentation is already available: http://wiki.squeak.org/squeak
Polishing did not happen.
o_O
I knew this would be next as soon as I had hit the "send" button. :-) Of course I mean in-image documentation. I know I know, there are also many unpolished places in there, but hey, this whole documentation initiative has just started, right?
You're right. Every detail matters to make good quality. *grin*
Ah well. Let there be a spell checker or not, I don't care. All I wanted to say is that we don't need one to get started.
Anyway, when are we getting HelpSystem integrated to the trunk again?
What is actually keeping us from doing it?
Best,
Michael
On 02.05.2010, at 15:21, Ian Trudel wrote:
A spell checker is among the tools I use to write documentation, articles, etc. I will survive if it's not in our HelpSystem but I know it will become an additional hurdle to me.
I guess nobody would mind having a spell checker, just don't rely on anyone else to make this her highest priority :)
Anyway, when are we getting HelpSystem integrated to the trunk again?
Err, you *do* know where the inbox is, right? ;)
- Bert -
My apologies Michael. This new initiative is indeed a good thing. :)
2010/5/2 Bert Freudenberg bert@freudenbergs.de:
I guess nobody would mind having a spell checker, just don't rely on anyone else to make this her highest priority :)
Anyway, when are we getting HelpSystem integrated to the trunk again?
Err, you *do* know where the inbox is, right? ;)
- Bert -
Bert,
I have installed the HelpSystem with the instructions from Torsten but I believe it uses SqueakSource. I will check in the inbox. The reason I would prefer contributing with the HelpSystem in the trunk is because it ensures my contribution is not in vain.
Am I allowed to put things into perspective once more? I have been writing often lately. I don't want to come off as annoying and everything I write is in all due respect.
What you are saying is that our community has a self-serving mentality (e.g. nobody will make such improvement a priority because it's not *their* priority) and you are suggesting me to do an unselfish act by writing documentation with unsuitable tools. A contradiction in logic. Or, let's say for the sake of the argument, I could be also self-serving and write articles about Squeak on my blog where I can do proper formatting, spell checking, include images, etc. and get instant popularity! **Blogger is the winner!**
That's basically how self-serving mentality works. The shortest and easiest path wins. Contributing on my blog would be good for Squeak (as a side effect) but doing so in-image documentation is better (best and direct). I am all right with contributing unselfishly because I believe a community cannot progress on the basis of selfishness. It's food-for-thoughts, right?
Ian.
On 02.05.2010, at 15:55, Ian Trudel wrote:
My apologies Michael. This new initiative is indeed a good thing. :)
2010/5/2 Bert Freudenberg bert@freudenbergs.de:
I guess nobody would mind having a spell checker, just don't rely on anyone else to make this her highest priority :)
Anyway, when are we getting HelpSystem integrated to the trunk again?
Err, you *do* know where the inbox is, right? ;)
- Bert -
Bert,
I have installed the HelpSystem with the instructions from Torsten but I believe it uses SqueakSource. I will check in the inbox. The reason I would prefer contributing with the HelpSystem in the trunk is because it ensures my contribution is not in vain.
Maybe you misunderstood. I was merely suggesting that the way to get HelpSystem into the trunk is by submitting it to the inbox first.
Am I allowed to put things into perspective once more? I have been writing often lately. I don't want to come off as annoying and everything I write is in all due respect.
What you are saying is that our community has a self-serving mentality (e.g. nobody will make such improvement a priority because it's not *their* priority) and you are suggesting me to do an unselfish act by writing documentation with unsuitable tools. A contradiction in logic.
I did not suggest any such thing. I just said you cannot *rely* on anyone else writing stuff for you. It may still happen. But as you could see from the comments of others, not everyone thinks that a missing spell-checker would block in-image documentation.
Or, let's say for the sake of the argument, I could be also self-serving and write articles about Squeak on my blog where I can do proper formatting, spell checking, include images, etc. and get instant popularity! **Blogger is the winner!**
That's basically how self-serving mentality works. The shortest and easiest path wins. Contributing on my blog would be good for Squeak (as a side effect) but doing so in-image documentation is better (best and direct). I am all right with contributing unselfishly because I believe a community cannot progress on the basis of selfishness. It's food-for-thoughts, right?
Not really, because we're not actually in disagreement I believe.
Everyone acts in their own interest. But we share some of the interests. That makes us a community. I like to think that our's works by the idea of reciprocity - the idea that if one gives freely, other will be inclined to do likewise. But it's the giving that counts, and it has to be unconditional. Even our license says so. Reciprocity does not involve demanding others give something first before one gives something back.
- Bert -
Hi Bert,
On Sun, May 2, 2010 at 3:28 PM, Bert Freudenberg bert@freudenbergs.de wrote:
Err, you *do* know where the inbox is, right? ;)
so ... I've been a bit busy and am just uploading four packages to the Inbox:
* Morphic-mha.433 insert Help Browser in Help menu (if it is present in the image) * HelpSystem-Core the core, without popping up the Help Browser after installation, but with updating the docking bar menus * HelpSystem-Tests just for good style * Squeak-Project-Help because it belongs
I don't know if I have broken any invariants. I know that Torsten primarily uses SqueakSource, so integration is a topic. Still, that step has been done.
(I'll send this message to the list once more to avoid it gets lost in the depths of this thread.)
Best,
Michael
Quality in general is *always* better served by a proofreader than by automatic spelling / grammar tools. This is part of why I want to do documentation in the trunk: because the trunk model gives us gatekeeping and peer review.
If someone finds something in one of my commits which reduces the quality of the docs, I'd treat that as build breakage, hamburger-hat and all.
If you want integrated spell checking, you're probably going to have to do the development work yourself, as it doesn't seem to be a priority to anyone else.
One thing I keep learning with software is YAGNI. http://c2.com/xp/YouArentGonnaNeedIt.html
On Sunday, May 2, 2010, Ian Trudel ian.trudel@gmail.com wrote:
2010/5/2 Michael Haupt mhaupt@gmail.com:
Hi Ian,
Hi Michael,
On Sun, May 2, 2010 at 2:37 PM, Ian Trudel ian.trudel@gmail.com wrote:
It is an unexpected comment from a German. My experience in the German market made it clear Germans demand high-quality writings — in German that is. The companies I have worked for were paying top dollars for near-perfect German writings, from advertisement to documentation.
see, that's what stereotypes are for: being reconsidered. :-)
I see. Companies however collect demographic data and it makes sense to consider such feedback. The important is to make a decision in a knowledgeable manner. Spell checker could be entirely excluded but at least it would be a decision taken in knowledge of its advantages and disadvantages. :)
I think it is much more important to get some documentation available. Polishing is always possible. There is no business contract involved here, and no $$$ lurking. At least not for me.
Some documentation is already available: http://wiki.squeak.org/squeak
Polishing did not happen.
o_O
My point is that we have more to gain to do it right from the ground up. The efforts required to interface with a spellchecker library is much less now than rewriting documentation later. ...
Correct spelling alone doesn't make good quality, does it?
You're right. Every detail matters to make good quality. *grin*
Best,
Michael
Quality is something I take at heart and I usually refrain from releasing anything that does not match a minimum quality standard as far as open source contribution goes and I release commercial work only when it matches my highest quality standard. A spell checker is among the tools I use to write documentation, articles, etc. I will survive if it's not in our HelpSystem but I know it will become an additional hurdle to me. I will probably end up writing in OpenOffice and transfer back in Squeak. Painful.
Anyway, when are we getting HelpSystem integrated to the trunk again? We could be typing in there instead. :)))
Ian.
Casey,
you made my point much better than I could. Thanks. Special thanks for the YAGNI pointer - I should have remembered that one. :-)
Best,
Michael
On Sun, May 2, 2010 at 8:48 PM, Casey Ransberger casey.obrien.r@gmail.com wrote:
Quality in general is *always* better served by a proofreader than by automatic spelling / grammar tools. This is part of why I want to do documentation in the trunk: because the trunk model gives us gatekeeping and peer review.
If someone finds something in one of my commits which reduces the quality of the docs, I'd treat that as build breakage, hamburger-hat and all.
If you want integrated spell checking, you're probably going to have to do the development work yourself, as it doesn't seem to be a priority to anyone else.
One thing I keep learning with software is YAGNI. http://c2.com/xp/YouArentGonnaNeedIt.html
On Sunday, May 2, 2010, Ian Trudel ian.trudel@gmail.com wrote:
2010/5/2 Michael Haupt mhaupt@gmail.com:
Hi Ian,
Hi Michael,
On Sun, May 2, 2010 at 2:37 PM, Ian Trudel ian.trudel@gmail.com wrote:
It is an unexpected comment from a German. My experience in the German market made it clear Germans demand high-quality writings — in German that is. The companies I have worked for were paying top dollars for near-perfect German writings, from advertisement to documentation.
see, that's what stereotypes are for: being reconsidered. :-)
I see. Companies however collect demographic data and it makes sense to consider such feedback. The important is to make a decision in a knowledgeable manner. Spell checker could be entirely excluded but at least it would be a decision taken in knowledge of its advantages and disadvantages. :)
I think it is much more important to get some documentation available. Polishing is always possible. There is no business contract involved here, and no $$$ lurking. At least not for me.
Some documentation is already available: http://wiki.squeak.org/squeak
Polishing did not happen.
o_O
My point is that we have more to gain to do it right from the ground up. The efforts required to interface with a spellchecker library is much less now than rewriting documentation later. ...
Correct spelling alone doesn't make good quality, does it?
You're right. Every detail matters to make good quality. *grin*
Best,
Michael
Quality is something I take at heart and I usually refrain from releasing anything that does not match a minimum quality standard as far as open source contribution goes and I release commercial work only when it matches my highest quality standard. A spell checker is among the tools I use to write documentation, articles, etc. I will survive if it's not in our HelpSystem but I know it will become an additional hurdle to me. I will probably end up writing in OpenOffice and transfer back in Squeak. Painful.
Anyway, when are we getting HelpSystem integrated to the trunk again? We could be typing in there instead. :)))
Ian.
-- Casey Ransberger
2010/5/2 Casey Ransberger casey.obrien.r@gmail.com:
Quality in general is *always* better served by a proofreader than by automatic spelling / grammar tools. This is part of why I want to do documentation in the trunk: because the trunk model gives us gatekeeping and peer review.
If someone finds something in one of my commits which reduces the quality of the docs, I'd treat that as build breakage, hamburger-hat and all.
Yes. Where are those proofreaders? The trunk breaks when someone screw up in the code. Will it break when documentation is screwed up? There is no safeguard as far as documentation is concerned. A spell checker is a safeguard.
We have a great case study in term of documentation: our wiki. Anybody can edit pages and it's easy. It just won't happen. The result is underwhelming.
If you want integrated spell checking, you're probably going to have to do the development work yourself, as it doesn't seem to be a priority to anyone else.
One thing I keep learning with software is YAGNI. http://c2.com/xp/YouArentGonnaNeedIt.html
Can we have this on the main page of the Squeak website, please?! Beside the download links. "You Aren't Gonna Need It" [but] "Download Now!". :)
Quote from the website:
“Even if you're totally, totally, totally sure that you'll need a feature later on, don't implement it now. Usually, it'll turn out either a) you don't need it after all, or b) what you actually need is quite different from what you foresaw needing earlier. “
Writing formal texts requires spell checking, whether it is automated or manually performed, which excludes a). You make it sounds like nobody ever use a hardcover dictionary or something. It's not going to be different later than now, as b) implies, because spell checking is not a new kind of feature; it is a widespread feature and every software that has it use it in a similar fashion. We already know the implications of a spell checker and it is not experimental in any way.
Besides, we even have a spell checker with a list of suggestions when a method is not written properly. Don't you ever use it?!
YAGNI makes sense in many instances but I believe this is one that it does NOT make sense. It seems to be used as a cognitive bias. It'd be much simpler if you'd just write “We're not going to have a spell checker, Ian. Give it up.” :)
Ian.
Hi Ian,
On Sun, May 2, 2010 at 10:23 PM, Ian Trudel ian.trudel@gmail.com wrote:
Yes. Where are those proofreaders?
'ere. One of 'em.
A spell checker is a safeguard.
The green horse would rather not have divorced the flabbergasting windscreen.
Happy spell checker. Unhappy reader. Unless someone expects something along the lines of Lewis Carroll, to whom I deeply bow.
Good night,
Michael
There are commit messages. I expect most people to commit to Inbox (I am not a Trunk developer, for example.) Just like with code, we have to hope that core developers will read the diffs before they push something from the Inbox to the Trunk.
And one can introduce code that breaks things without introducing an obvious build breakage. It's a shame that natural language is so hard to write tests for:)
I'm not saying I don't think a spell checker is a good idea. I'm saying that I wouldn't block contributions of documentation because we don't have a spell checker. In fact, I'd even go as far as saying that a spelling error in an otherwise good comment where there previously had been none is still an improvement.
Let me cut to the chase and then kill the thread:
If you feel so strongly that we should have an integrated spell checker, why don't you implement or integrate one, and then push it to the Inbox? I would *love* to be able to spell check things in Squeak.
I'm not going to implement one, because my spelling is generally pretty good, and I'd rather spend my time on other things; e.g., writing class comments.
On Sun, May 2, 2010 at 1:23 PM, Ian Trudel ian.trudel@gmail.com wrote:
2010/5/2 Casey Ransberger casey.obrien.r@gmail.com:
Quality in general is *always* better served by a proofreader than by automatic spelling / grammar tools. This is part of why I want to do documentation in the trunk: because the trunk model gives us gatekeeping and peer review.
If someone finds something in one of my commits which reduces the quality of the docs, I'd treat that as build breakage, hamburger-hat and all.
Yes. Where are those proofreaders? The trunk breaks when someone screw up in the code. Will it break when documentation is screwed up? There is no safeguard as far as documentation is concerned. A spell checker is a safeguard.
We have a great case study in term of documentation: our wiki. Anybody can edit pages and it's easy. It just won't happen. The result is underwhelming.
If you want integrated spell checking, you're probably going to have to do the development work yourself, as it doesn't seem to be a priority to anyone else.
One thing I keep learning with software is YAGNI. http://c2.com/xp/YouArentGonnaNeedIt.html
Can we have this on the main page of the Squeak website, please?! Beside the download links. "You Aren't Gonna Need It" [but] "Download Now!". :)
Quote from the website:
“Even if you're totally, totally, totally sure that you'll need a feature later on, don't implement it now. Usually, it'll turn out either a) you don't need it after all, or b) what you actually need is quite different from what you foresaw needing earlier. “
Writing formal texts requires spell checking, whether it is automated or manually performed, which excludes a). You make it sounds like nobody ever use a hardcover dictionary or something. It's not going to be different later than now, as b) implies, because spell checking is not a new kind of feature; it is a widespread feature and every software that has it use it in a similar fashion. We already know the implications of a spell checker and it is not experimental in any way.
Besides, we even have a spell checker with a list of suggestions when a method is not written properly. Don't you ever use it?!
YAGNI makes sense in many instances but I believe this is one that it does NOT make sense. It seems to be used as a cognitive bias. It'd be much simpler if you'd just write “We're not going to have a spell checker, Ian. Give it up.” :)
Ian.
2010/5/2 Casey Ransberger casey.obrien.r@gmail.com:
If you feel so strongly that we should have an integrated spell checker, why don't you implement or integrate one, and then push it to the Inbox? I would *love* to be able to spell check things in Squeak.
Squeak is a complex system, more than some of us would admit. I don't think I will be contributing code in a nearby future. Surveys, articles, installers, documentation and alike are likely to be more suitable to me and it seems to be a working formulae for me.
I am reading the comment from Bert and I believe there is a misunderstanding. When someone writes documentation for something he or she understands, he or she does not have any immediate need for this documentation. The reciprocity Bert mentioned is nonexistent. I can document something for another person but this person won't implement tools for documentation.
Listen up. There is no need to stretch the conversation beyond its necessity. I will respect the decision of the community and I will contribute as I can.
Ian.
On 5/2/10, Ian Trudel ian.trudel@gmail.com wrote:
2010/5/2 Casey Ransberger casey.obrien.r@gmail.com:
If you feel so strongly that we should have an integrated spell checker, why don't you implement or integrate one, and then push it to the Inbox? I would *love* to be able to spell check things in Squeak.
Squeak is a complex system, more than some of us would admit.
YES.
....
I am reading the comment from Bert and I believe there is a misunderstanding. When someone writes documentation for something he or she understands, he or she does not have any immediate need for this documentation.
But maybe for other documentation :-)
The reciprocity Bert mentioned is nonexistent.
The reciprocity _is_ existent.
I document class A which I understand and you document class B which I do not understand....
Regards Hannes
squeak-dev@lists.squeakfoundation.org
-
Andreas Raab -
Bert Freudenberg -
Casey Ransberger -
Casimiro de Almeida Barreto -
Hannes Hirzel -
Hans-Martin Mosner -
Ian Trudel -
Josh Gargus -
K. K. Subramaniam -
Michael Haupt -
Ralph Johnson -
Rita Freudenberg -
Stéphane Rollandin -
Tobias Pape