httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Slive <jos...@slive.ca>
Subject Re: Tips for nascent doc effort
Date Fri, 03 May 2002 15:41:31 GMT
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


Mime
View raw message