Re: Nine Months in Six Months

[Shaun McCance <shaunm gnome org>]

On Sun, 2006-09-10 at 10:24 +1200, Matthew Paul Thomas wrote:
> On Sep 10, 2006, at 8:31 AM, Nickolay V. Shmyrev wrote:
> > ...
> > [Shaun McCance wrote:]
> >>
> >> But now you want all these programmers to assemble their 
> >> documentation piecemeal as they add features?
> >>
> >> Even if they all had perfect English (which they don't), and even if 
> >> they were all really good at explaining things (which they aren't), 
> >> this would still produce bad documentation.  Why?  Because it would 
> >> only ever produce "What's this?" documents, and never "How do I?" 
> >> documents.
> >>
> >> I find myself shooting down this idea every single release cycle.
> > ...
> 
> I humbly suggest that as long as you keep shooting it down, you will 
> keep having the problem of not enough time to write "documentation".
> 
> Calling it "documentation" almost enforces the problem, suggesting that 
> you're documenting something that has already been written. But just as 
> with the interaction design, and just as with the test suite, you'll 
> often get better results if the help for a feature is written before 
> the code. The goal of all these disciplines is to maximize the 
> proportion of people who use the software successfully, and it makes 
> little sense to treat any of them as completely separate from the 
> others.
> 
> I haven't seen anyone claim that programmers are usually good at 
> writing help; it would be surprising if they were. But whenever they're 
> not, they should team up with someone who is. Just as they should team 
> up with someone good at interaction design, and someone good at 
> thinking up test cases. For each module in Gnome (as I said on 
> gnome-doc-list last month), you should be able to ask, "who is the 
> maintainer, who is the interaction designer, who is the QA engineer, 
> and who is the help author", and get three or four distinct answers.

I don't disagree.  I think this is generally a very good
way to develop software.  But I also think it's not what
people generally mean when they propose the "everything
must be documented before commit" thing.

Your proposal means that every project has an integrated
team that works together on all decisions.  They all sit
down in front of a whiteboard and address some issue.
All of them work together to design a solution, each of
them with a different perspective.  Then the writer can
write while the programmer codes, because they both know
how the solution is supposed to work.  Then they compare
results to check for misunderstandings and different
interpretations.

But that's not what people will get out of a requirement
like "all changes must be documented before you commit".
They'll just write code like they always do, and then
resent the fact that they can't commit it because they
have to find somebody to write documentation.  People
will just commit whatever minimal amount is necessary
to fulfill the requirements, and we'll end up with
interface descriptions in DocBook.

Your proposal is a complete change in the way we do
software.  I'm not saying it's a bad method.  In fact,
I think it's a great method.  But I'm not sure we can
do that kind of gear shift in a project with as much
momentum as Gnome.

Here are some issues we'd encounter:

* Many programmers wouldn't be very receptive to the
  idea of relinquishing that much control, especially
  because:
* We'd have a hard time finding enough designers and
  writers and testers to get the teams functioning,
  in part because because:
* A lot of non-code contributors have a very difficult
  time having their computers run our unstable series.
* Concurrent development (branches and such) would be
  pretty difficult, mostly because of the merging pains
  in monolithic documents.  Mallard would help this.

Also, Gnome is a big aggregate, and not everything can
be done at the module level.  There is a non-negligable
amount of documentation work that has to be done at the
birds-eye level.  We could have sort of meta-coordination
of teams here, but I fear the entire project would just
grind to a halt every time we hit a bottleneck.

And that, I think, is the crux of my reservations about
this development style for Gnome.  In a community like
Gnome, we have to be very careful to avoid bottlenecks.
A development procedure like this in a community like
Gnome is very prone to bottlenecks.

--
Shaun