No subject

after it's fully baked, but then you lose any opportunity to
influence its development. So if, as you referred to earlier, the terms
that developers use don't make sense to librarians, a good technical
writer has the ability to flag problematic terms during development and
improve the quality of the resulting product.

> >   The trick is to be able to describe the concepts clearly
> > ("So, serials are composed of the following elements: distributions,
> > which are X and interact with libraries like so; streams, which are Y;
> > subscriptions, which are Z; issuances, which are FOO") and then list the
> > tasks and the corresponding places in which those tasks are
> > accomplished.
> >
> >  From there, documenting how to perform a task on a given screen should
> > be close to mechanical. ("Step 1. In the Foo panel, select the target
> > library from the Bar widget. The Frambazzle dialog opens.... Step 2...")
> This is a fallacy of composition - if I have all the concepts of the 
> development outlined and described then the development is clear and 
> documentation practically writes itself.

No, this is not a rhetorical device, and I'm not talking about
describing the concepts of the development. The division into concepts,
tasks, and reference material is how many current technical writing
communities ("topic oriented documentation") categorized their efforts
at a high level - or at least, that was the state of things 5 years ago.
I'm sure other schools of thought have evolved since then.

> Writing good, useful documentation isn't about describing the 
> components.  And, in the course of community development, those 
> components often change, which is the point I'm trying to make.  The 
> overall end result doesn't change (ordering items via EDI from Baker and 
> Taylor) but steps, processes, names, etc. *do* change.  Why?  Because 
> we're doing community development and things change based on feedback.

It sounds like we're arguing the same thing, except that I'm arguing
that 1) there's no reason to hold back documentation that is under
development and 2) it's better for the product as a whole if the
documentation is under active development while the code is still under
development, because the docs can influence the code and the code can
more closely influence the docs, and 3) I'm talking about concepts, not
software components.

> However, providing the outline and basic structures for feedback from 
> the community during development is useful for development - but I don't 

So by outline, you mean enough documentation to let the community know
what is supposed to be capable and what is supposed to be working and
how they're supposed to be using this thing that is placed in front of
them, so that they can provide useful feedback?

> think as useful for documentation.  And if the place where the outline 
> and structure is available to the community is updated with changes and 
> progress, then that becomes VERY useful when the time comes to document 
> the feature.
> > A colleague of mine used to say "If the UI's a dog, the help will bark."
> > If the help is barking early on in the documentation process, that might
> > be early enough to suggest that some change would be good. If the
> > documentation is held off until the end, though, then that's a missed
> > opportunity for feedback.
> I disagree. 

Eh? You disagree that that's a missed opportunity for feedback? I don't
get it. I'm not saying that a tech writer's feedback is the only way,
I'm just saying it is a way.

> There are ways to update the path of development which 
> allows for feedback without creating documentation- see above.  Creating 
> documentation before the development is close to being finished is 
> putting the cart before the horse.  I don't write a summary of my summer 
> reading program's success on the second week of the program, I wait 
> until the last week.   But I do make notes and update my data along the 
> way...

Hey, check out
http://www.agilemodeling.com/essays/agileDocumentation.htm#IssuesWithDocumentation
which agrees with you on timing for "user documentation" (which is
primarily what we're talking about), and again, going back to what I had
asked for and Robert asked for, getting the "Here's the problem we need
solved / here's how we propose solving it" documents _after_ a contract
has been signed (to prevent nefarious types can swoop in and swipe the
intellectual effort that went into coming up with a solution) would be a
great start - and if the notes and data that you were updating along the
way were able to be shared, so much the better.

> > Now, getting the documentation out at the time of release?  That should
> > be an achievable goal for Equinox; however, I can't speak for the
> > community developers - and all the developers should be held to the same
> > standard.  Since there isn't a "client" who is commissioning the work,
> > perhaps the community developers could use DIG as they go along their
> > development path to provide testing and documentation.
> 
> > I hope that Equinox doesn't see itself as being separate from DIG or
> > community development. Crazy idea: if part of the release standard was
> > "no new feature goes into the official release without adequate
> > documentation" and DIG was the arbiter of what "adequate" meant, then it
> > would be a level playing field for all.
> Dan, I'm sorry if my comments weren't clear.  Let me reiterate: Equinox 
> has the in-house tools to provide basic documentation for every 
> development project they are undertaking going forward.  We believe we 
> owe that to the community.  The other developers in the community 
> (vendor or non-vendor) will need a mechanism for providing documentation 
> with their development.  I think if the community agrees that DIG should 
> be the arbiter of what development goes into a release based on 
> documentation we should at least agree on a basic well-defined standard.

I at least agree that we should agree that the community should agree
that DIG should be the arbiter of what "adequate documentation" is.
Whether the lack of adequate docs should be one of the non-code factors
that would prevent future code from landing in an official release,
that's a large matter that is probably more appropriate for a different
forum entirely (or fora, for that matter)...
 
> > Keeping features out of an official release due to a lack of
> > documentation may be a crazy idea, yes. But a boy can dream. I think
> > these (who decides what's in an official release? Hey, should the docs
> > be part of the release tarball? Or at least offered for download as a
> > separate tarball?) are very healthy discussions to have. Development is
> > development, whether it's paid for via a contract, or paid for via a
> > salaried position, or paid for via somebody's volunteer time when their
> > kids are asleep and they could be doing 1000 other things. Documentation
> > is exactly the same, and is arguably as valuable as the code underlying
> > the features it explains.
> >
> I don't think anybody is arguing that documentation is important.  And 
> the discussion of how to handle the documentation aspect of Evergreen 
> development is past due.  I will be the first person to admit that we 
> regret not being able to provide excellent documentation for every 
> feature we've worked on.  We really are committed to working with 
> everyone in the community to resolve this in a way that makes sense.

Sounds great! I'm encouraged by our collective recognition that
delivering functionality without documentation in past releases was
probably not a great idea on our part (collectively) and am very
grateful to DIG for having made up so much ground in the past year.