Tips for nascent doc effort

[Diana Shannon <te...@mac.com>]

Hello!

I've been perusing your archives, trying to glean some advice as to how 
this group's experience might aid a new effort to improve documentation 
for Apache's Cocoon project. I'd be grateful for *any* tips, on- or 
off-list, that you may have about the following:

1. I assume Apache documentation-related discussions began on a list 
like apache-httpd-dev. If so, when did it move to a separate docs lists? 
How many people, particularly developers, subscribed/participated 
initially? I've been looking into a number of open source documentation 
initiatives, past and present, lately. Sadly, many of them die. A number 
of people within the Cocoon community are worried about moving 
doc-related discussions off cocoon-dev prematurely, fearing developers 
will disconnect from the documentation gestation process altogether. Was 
this a concern for you? How did you manage the transition? How do you 
keep developers or SMEs (subject matter experts) involved in the 
documentation effort?

2. I'm hoping to address a number of problems with insufficient docs by 
encouraging community contributions of faqs, howtos, tutorials, case 
studies, etc. I'm working on how-to guidelines for all of these types, 
schemas, and templates. Our proposed process includes the following 
steps:
a. Author consults topic status list (a web page on cocoon web site) to 
make sure no other draft on this topic is in process. Author sends patch 
via bugzilla to topic-status.xml to "claim" the topic.
b. Author reads the appropriate how-to author a <document-type-name /> 
document
c. Following guidelines and templates, author submits proposed document 
outline via Bugzilla.
d. Committer adds new document outline to document scratchpad area in 
cocoon cvs. Once in cvs, announcement sent to cocoon-dev, e.g. "[REVIEW] 
this-document-name".
e. SMEs, editors, and all interested parties make comments
f. Author writes document draft, based on revised outline.
g. Author submits draft as patch via Bugzilla. Committers update 
document in scratchpad.
h. Once in the CVS all interested persons address holes and other issues.
i. QA testing begins. Revisions performed as necessary.
j. After a vote, document moves out of scratchpad and into
the distribution proper.
k. Community/author submits patches as appropriate via
the normal Bugzilla process.

What do you think about this process? Some think it's too formal, has 
too many hoops. They think authors will be discouraged by it and not 
contribute. I'm not sure the pure cvs model works for documentation as 
it does for code. For example, when code has holes, it breaks or 
performs unacceptably. People have a great incentive to fix it. When 
documentation has holes, potential users and evaluators give up. There's 
a much weaker incentive structure for fixing documentation. I'm hoping 
such a process will minimize these problems during initial development 
and not rely so much on maintenance. What do you think?

3. Are there any disadvantages in having a separate cvs branch for docs?

4. I downloaded your cvs, but it isn't clear how you manage the document 
life cycle (draft -> iterations -> release). Is this managed through 
strictly through cvs versioning or included as some form of meta data 
within the docs themselves?

Any other tips, hard-earned advice very welcome. And please let me know 
if anything we are doing might prove useful to your efforts.

Thanks for reading!

Diana Shannon
shannon@terracare.com
(still waiting for shannon@apache.org to start functioning...)


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: Tips for nascent doc effort

[Cliff Woolley <jw...@virginia.edu>]

Just thought I'd give you a developer's perspective on this one to add to
what Joshua said.


On Fri, 3 May 2002, Diana Shannon wrote:

> initiatives, past and present, lately. Sadly, many of them die. A number
> of people within the Cocoon community are worried about moving
> doc-related discussions off cocoon-dev prematurely, fearing developers
> will disconnect from the documentation gestation process altogether. Was
> this a concern for you? How did you manage the transition?


As Joshua said, the primary responsibility lies with the developers,
particularly in API documentation (which we keep in the header files
themselves in Doxygen/Scandoc format to make it hard to forget to update
them).  It would be nice if developers would document new configuration
directives they add or ones they modify, that's SUPPOSED to be a
requirement.  We often forget.  Fortunately this kind of change doesn't
happen very often.  That's one way in which the docs project can help us
out... they keep a much-needed watchful eye on us.  :)

> How do you keep developers or SMEs (subject matter experts) involved in
> the documentation effort?

I guess I already answered part of this.  The flip side is that I know
there are many developers (including myself) who, while we don't actively
go about improving the documentation, do "listen in" on this list.
Inter-group communication seems to be the key.  The docs people (or at
least Joshua) listen to what we're doing, and we listen to what the docs
project is doing.

> Our proposed process includes the following steps: a. Author consults
> topic status list (a web page on cocoon web site) to make sure no other
> draft on this topic is in process. Author sends patch via bugzilla to
> topic-status.xml to "claim" the topic. b. Author reads the appropriate
> how-to author a <document-type-name /> document c. Following guidelines
> and templates, author submits proposed document outline via Bugzilla.
> [snip]
>
> What do you think about this process

Wow, that's quite a lengthy process.  I'm in the "think it's too formal,
has too many hoops" camp, I think.  All too often, both in the docs
project and in the code itself, it's not uncommon, unfortunately, to have
worked on something and to *beg* for someone else to review your work, and
nobody does.  There's just too much work to go around to have that much of
an editorial process.  Volunteer open-source projects don't work quite the
same way as professional publishing companies do in that regard.  I agree
with Joshua that you will probably find that so much red tape gets in the
way of frequent contributors who just want to get things done.  If the
code itself had that much review, yes it would be better, but it would
also never GO anywhere.

I will say that the straight-up CVS approach has worked incredibly well
for this docs project.  Commit-then-review is just as appropriate for a
docs project as it is for the code itself IMO, and this project stands as
proof of concept.

My only big thought is that you seem to imply that once a document is
written, reviewed, and released, then that can just be "it" if you do it
carefully.  I'd counter that that doesn't work when documenting a moving
target.  By necessity, just as much if not more work must be done to keep
the existing documentation up to date with the code as is done in adding
new documentation.  While the process you describe would work great if the
documentation could be "write once," I think you'll find that's not the
case.

Hope this helps,
Cliff

--------------------------------------------------------------
   Cliff Woolley
   cliffwoolley@yahoo.com
   Charlottesville, VA





---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: Tips for nascent doc effort

[Joshua Slive <jo...@slive.ca>]

Hmmm... tough questions...

On Fri, 3 May 2002, Diana Shannon wrote:
>
> 1. I assume Apache documentation-related discussions began on a list
> like apache-httpd-dev. If so, when did it move to a separate docs lists?

I believe it was in summer 2000, which would make is about five years
after the apache project started if my calculations are not too far off.
There had been a docs list for a long time before that, but it hadn't been
used for much until Ken got things off the ground by splitting the cvs
repos.

> How many people, particularly developers, subscribed/participated
> initially?

I believe there were several hundred subscribers, but only a dozen or less
active participants.  That is probably still true today.  A good chunk,
but certainly not all of the core developers participated initially and
still do.

> I've been looking into a number of open source documentation
> initiatives, past and present, lately. Sadly, many of them die. A number
> of people within the Cocoon community are worried about moving
> doc-related discussions off cocoon-dev prematurely, fearing developers
> will disconnect from the documentation gestation process altogether. Was
> this a concern for you? How did you manage the transition? How do you
> keep developers or SMEs (subject matter experts) involved in the
> documentation effort?

In my opinion, the primary responsibility for documenting the server must
rest with the developers.  If you code it, you should doc it.  I don't
think the existance of a doc project changes that.  The docs project
should be a suplemental effort to manage and improve the docs, not a
replacement for proper developer contributions.

> What do you think about this process? Some think it's too formal, has
> too many hoops. They think authors will be discouraged by it and not
> contribute. I'm not sure the pure cvs model works for documentation as
> it does for code. For example, when code has holes, it breaks or
> performs unacceptably. People have a great incentive to fix it. When
> documentation has holes, potential users and evaluators give up. There's
> a much weaker incentive structure for fixing documentation. I'm hoping
> such a process will minimize these problems during initial development
> and not rely so much on maintenance. What do you think?

That is WAY more structure than we have.  I suppose some structure is
helpful in that it gives newcomers an easy way to get started.  But it
also could stymie the efforts of people who just want to get things done.
I don't have any advice for you, since we just manage things the same as
coders: "commit then review", with large changes and ideas posted to the
list first.

> 3. Are there any disadvantages in having a separate cvs branch for docs?

Just that it can make things more difficult for coders if it is not done
carefully.

>
> 4. I downloaded your cvs, but it isn't clear how you manage the document
> life cycle (draft -> iterations -> release). Is this managed through
> strictly through cvs versioning or included as some form of meta data
> within the docs themselves?

CVS only.  Normally new docs are posted to this list first for review
before they are committed.

Joshua.


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org