[Squeak-doc] Roadmap proposal.

[Ron Teitelbaum]

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 at lists.squeakfoundation.org [mailto:squeak-doc-
> bounces at lists.squeakfoundation.org] On Behalf Of max at nbtsc.org
> Sent: Thursday, April 05, 2007 3:12 PM
> To: squeak-doc at 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