[Squeak-doc] Roadmap proposal.

[Matthew Fulmer]

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. 

-- 
Matthew Fulmer -- http://mtfulmer.wordpress.com/
Help improve Squeak Documentation: http://wiki.squeak.org/squeak/808