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 <[hidden email]> 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.html 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 |
In reply to this post by Bert Freudenberg
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 - > > > |
In reply to this post by Andreas.Raab
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 |
In reply to this post by Casey Ransberger-2
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/ |
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 <[hidden email]> wrote: Hello Casey, -- Casey Ransberger |
2010/4/30 Casey Ransberger <[hidden email]>:
> 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:) > 1. 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. > 2. 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. > 3. 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. -- http://mecenia.blogspot.com/ |
Ian, thanks. Comments inline.
On Fri, Apr 30, 2010 at 1:36 PM, Ian Trudel <[hidden email]> wrote: 2010/4/30 Casey Ransberger <[hidden email]>: 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
Agreed. I just sent another message about this.
I think examples raise the quality of class comments. Absolutely.
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. Thanks for your feedback! -- Casey Ransberger |
2010/4/30 Casey Ransberger <[hidden email]>:
> 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. :) >> > 3. 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. -- http://mecenia.blogspot.com/ |
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. -- http://mecenia.blogspot.com/ |
Hi Ian,
On Sun, May 2, 2010 at 2:37 PM, Ian Trudel <[hidden email]> 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 <[hidden email]>:
> Hi Ian, Hi Michael, > On Sun, May 2, 2010 at 2:37 PM, Ian Trudel <[hidden email]> 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. -- http://mecenia.blogspot.com/ |
Hi Ian,
On Sun, May 2, 2010 at 3:21 PM, Ian Trudel <[hidden email]> 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 |
In reply to this post by Ian Trudel-2
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 <[hidden email]>: > 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. -- http://mecenia.blogspot.com/ |
In reply to this post by Bert Freudenberg
Hi Bert,
On Sun, May 2, 2010 at 3:28 PM, Bert Freudenberg <[hidden email]> 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 |
In reply to this post by Ian Trudel-2
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 <[hidden email]>: >> 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 - |
In reply to this post by Ian Trudel-2
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 <[hidden email]> wrote: > 2010/5/2 Michael Haupt <[hidden email]>: >> Hi Ian, > > Hi Michael, > >> On Sun, May 2, 2010 at 2:37 PM, Ian Trudel <[hidden email]> 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. > -- > http://mecenia.blogspot.com/ > > -- Casey Ransberger |
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 <[hidden email]> 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 <[hidden email]> wrote: >> 2010/5/2 Michael Haupt <[hidden email]>: >>> Hi Ian, >> >> Hi Michael, >> >>> On Sun, May 2, 2010 at 2:37 PM, Ian Trudel <[hidden email]> 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. >> -- >> http://mecenia.blogspot.com/ >> >> > > -- > Casey Ransberger > > |
Free forum by Nabble | Edit this page |