A couple of thoughts on the Doc Project:
First, as Matthew points out, the current state of Squeak's documentation is really a "political" (I'd say "cultural") problem, not so much a technical one. I see us maybe getting a bit distracted with all the cool technologies that can be brought to bear on the challenge of having good docs. Technical solutions to cultural problems can only really work to the extent that they are built on a solid grasp of the culture. We're all (to varying extents) newbies on this team, so it behooves us to learn the history, attitudes, and values of the community we're trying to be a useful part of.
Squeak's culture, in my limited experience, is messy but friendly, not so different from other mid-size open source projects. We're smart, well-meaning people, scattered around the world. Some are ideologues, some pragmatists. We all have slightly different visions of what we want, and we collaborate to the extent that these visions overlap.
However, Smalltalk is different from other programming languages in a number of ways, one of which I think is especially pertinent here, which brings me to my second point:
Smalltalk was always intended to be a uniquely user-friendly and readable language, built on a few powerful concepts, with a minimum of arbitrary syntax. I think that the reason the more experienced Squeakers are so lackadaisical about documentation is that well-written Smalltalk IS its own documentation. This is a very good thing!
With this in mind, I think that an important guiding principle for this project should be to teach newcomers to read and understand the code first and foremost. Seen in this light, the tutorials are more than just the tip of the iceberg; they may be a significant fraction of the battle. Once a newbie like myself learns to read code to answer specific questions, and learns to use the IDE tools effectively, the remaining need for documentation is mostly for relatively terse, high-level conceptual descriptions of larger systems like Morphic.
I would be in favor of focusing on the existing class and method comments, to make them as accurate and helpful as possible, before we go building an extensive parallel doc system. This might be harder or less fun, but I'm convinced it will be more useful in the end. I think that, having done that, there will still be a need for a Magic Book, but the scope of it may be reduced considerably. Also, we'll probably produce better documentation for having taken the time to really get familiar with what we're documenting.
Sent via BlackBerry from T-Mobile
Hi all,
I'm late to this discussion so forgive me for not going back and reading everything. I found this email to be right on point.
I had a team of about 40 developers. I thought it would really be nice if we could build some tools that allowed people to interact with the system to create documentation. Some of the things we created worked and some didn't.
Here's what we created.
First we created a wiki page for comments. From any method we hit one key and brought up a wiki page about that method. On the page if it didn't exist we populated the page with a template. We wanted an explanation of what it does, and examples of how to use it, questions, comments, other methods that were like this one.
We created it and it went nowhere. Most developers said it wasn't useful because there were comments on the method and browsing senders is a much better way to find examples.
Next we created a way from our application to add user documentation. On any screen or on any input field we programmed it to bring up a robohelp file that could be added to. This worked for a while because the people that needed the documentation were responsible for asking the questions, finding the answers and writing the comments.
I saw somewhere, but I don't remember where now, documentation where every page had a comment area on it. Comments from end users about what didn't make sense or better explanations showed up frequently and the document team periodically went through the comments and changed the documentation.
Then we decided that having the users documenting on there own was not such a good idea because they sometimes got it wrong. So we added a workflow. Users could automatically send questions about a screen to the author of code, and the author would try to answer the question, or would be responsible for getting the answer back to the user. Then the user would write up documentation and send it back to the author to approve.
I'm not sure how much of this worked because we had actual users of an application, where as in Squeak we have users of a programming language, but it is worth considering that having tools that people do not use, is wasted time. By the way all the documentation efforts broke down as the schedule was squeezed within an inch of its life.
Sorry if I said something that was already said previously. I agree with Max that you should focus on things developers will do and those things that will add the most value. Cool tools are not so cool if nobody uses them.
Ron Teitelbaum
-----Original Message----- From: squeak-doc-bounces@lists.squeakfoundation.org [mailto:squeak-doc- bounces@lists.squeakfoundation.org] On Behalf Of max@nbtsc.org Sent: Thursday, April 05, 2007 3:12 PM To: squeak-doc@lists.squeakfoundation.org Subject: [Squeak-doc] Roadmap proposal.
A couple of thoughts on the Doc Project:
First, as Matthew points out, the current state of Squeak's documentation is really a "political" (I'd say "cultural") problem, not so much a technical one. I see us maybe getting a bit distracted with all the cool technologies that can be brought to bear on the challenge of having good docs. Technical solutions to cultural problems can only really work to the extent that they are built on a solid grasp of the culture. We're all (to varying extents) newbies on this team, so it behooves us to learn the history, attitudes, and values of the community we're trying to be a useful part of.
Squeak's culture, in my limited experience, is messy but friendly, not so different from other mid-size open source projects. We're smart, well- meaning people, scattered around the world. Some are ideologues, some pragmatists. We all have slightly different visions of what we want, and we collaborate to the extent that these visions overlap.
However, Smalltalk is different from other programming languages in a number of ways, one of which I think is especially pertinent here, which brings me to my second point:
Smalltalk was always intended to be a uniquely user-friendly and readable language, built on a few powerful concepts, with a minimum of arbitrary syntax. I think that the reason the more experienced Squeakers are so lackadaisical about documentation is that well-written Smalltalk IS its own documentation. This is a very good thing!
With this in mind, I think that an important guiding principle for this project should be to teach newcomers to read and understand the code first and foremost. Seen in this light, the tutorials are more than just the tip of the iceberg; they may be a significant fraction of the battle. Once a newbie like myself learns to read code to answer specific questions, and learns to use the IDE tools effectively, the remaining need for documentation is mostly for relatively terse, high-level conceptual descriptions of larger systems like Morphic.
I would be in favor of focusing on the existing class and method comments, to make them as accurate and helpful as possible, before we go building an extensive parallel doc system. This might be harder or less fun, but I'm convinced it will be more useful in the end. I think that, having done that, there will still be a need for a Magic Book, but the scope of it may be reduced considerably. Also, we'll probably produce better documentation for having taken the time to really get familiar with what we're documenting.
Sent via BlackBerry from T-Mobile
On Thu, Apr 05, 2007 at 03:55:33PM -0400, Ron Teitelbaum wrote:
Hi all,
I'm late to this discussion so forgive me for not going back and reading everything. I found this email to be right on point.
Your not late. The discussion has been mostly through private messages on freenode. It is just now going public.
I had a team of about 40 developers. I thought it would really be nice if we could build some tools that allowed people to interact with the system to create documentation. Some of the things we created worked and some didn't.
Here's what we created.
First we created a wiki page for comments. From any method we hit one key and brought up a wiki page about that method. On the page if it didn't exist we populated the page with a template. We wanted an explanation of what it does, and examples of how to use it, questions, comments, other methods that were like this one.
We created it and it went nowhere. Most developers said it wasn't useful because there were comments on the method and browsing senders is a much better way to find examples.
Next we created a way from our application to add user documentation. On any screen or on any input field we programmed it to bring up a robohelp file that could be added to. This worked for a while because the people that needed the documentation were responsible for asking the questions, finding the answers and writing the comments.
I saw somewhere, but I don't remember where now, documentation where every page had a comment area on it. Comments from end users about what didn't make sense or better explanations showed up frequently and the document team periodically went through the comments and changed the documentation.
Then we decided that having the users documenting on there own was not such a good idea because they sometimes got it wrong. So we added a workflow. Users could automatically send questions about a screen to the author of code, and the author would try to answer the question, or would be responsible for getting the answer back to the user. Then the user would write up documentation and send it back to the author to approve.
I'm not sure how much of this worked because we had actual users of an application, where as in Squeak we have users of a programming language, but it is worth considering that having tools that people do not use, is wasted time. By the way all the documentation efforts broke down as the schedule was squeezed within an inch of its life.
Sorry if I said something that was already said previously. I agree with Max that you should focus on things developers will do and those things that will add the most value. Cool tools are not so cool if nobody uses them.
I agree completely. Writing documentation and establishing a work flow is the first step. Tools will follow and will be used to help automate, but not replace, the work flow. Porting documentation to a particular tool is easier than writing the documentation, and the hard problem should be solved first. It can later be ported to Sophie, Pier, or something else once the need is better established.
On Thu, Apr 05, 2007 at 07:12:10PM +0000, max@nbtsc.org wrote:
<snip>
Smalltalk is different from other programming languages in a number of ways, one of which I think is especially pertinent here, which brings me to my second point:
Smalltalk was always intended to be a uniquely user-friendly and readable language, built on a few powerful concepts, with a minimum of arbitrary syntax. I think that the reason the more experienced Squeakers are so lackadaisical about documentation is that well-written Smalltalk IS its own documentation. This is a very good thing!
This is exactly correct. I could not find a good way to say this, but I intended to make that point.
With this in mind, I think that an important guiding principle for this project should be to teach newcomers to read and understand the code first and foremost. Seen in this light, the tutorials are more than just the tip of the iceberg; they may be a significant fraction of the battle. Once a newbie like myself learns to read code to answer specific questions, and learns to use the IDE tools effectively, the remaining need for documentation is mostly for relatively terse, high-level conceptual descriptions of larger systems like Morphic.
I would be in favor of focusing on the existing class and method comments, to make them as accurate and helpful as possible, before we go building an extensive parallel doc system. This might be harder or less fun, but I'm convinced it will be more useful in the end. I think that, having done that, there will still be a need for a Magic Book, but the scope of it may be reduced considerably. Also, we'll probably produce better documentation for having taken the time to really get familiar with what we're documenting.
This is a very important point, and one I completely overlooked in my road map proposal. You are absolutely right. Class and method comments are the best tool currently existing for documenting Squeak behavior, better than Swiki, Pier, and Sophie for what they do. Comments have all the critical features we need for a useful documentation system: - They fit into packages and can be distributed - They are integrated into the existing Squeak tool set - They can be easily searched, modified, and distributed
Ignoring comments would be a fatal mistake to any documentation effort, and I was in the process of making that mistake. Thank you Thank you Thank you for calling my bluff.
This observation makes my road map proposal look a lot more realistic. Comments, rather than some combination of Sophie, Pier, or something else, should be the ultimate holders of the document republishing effort that Paul Bennett has begun. We already have all the tools we need to solve our documentation problems!
It also greatly simplifies the implementation of the web/image duality I would like to have. By creating a Magritte Description for comments, Pier would be able to create an entire book by stringing together class comments. This book could be viewed in-image or on the web, and editing any of the three views (comments, web book, image book) would update the other two.
I cannot believe I overlooked comments in my proposal. Thank you for reminding me. I will correct this immediately.
squeak-doc@lists.squeakfoundation.org
-
Matthew Fulmer -
max＠nbtsc.org -
Ron Teitelbaum