Mailing List Archive

(originally sent only to apache-docs)

On Fri, 21 Apr 2000, Rodent of Unusual Size wrote:

> Well, the move of the Apache HTTP server documentation out of
> the code repository and into a separate area where coders and
> non-coders alike can work on it should happen to-day.
>
> One of the issues with this is where update messages should go.
> That is, when someone adds, removes, or changes a file, the
> system sends a report of the details somewhere.. but in this
> case, where?
>
> I propose that it be sent to this list, <apache-docs@apache.org>.
> At least to start. If it ends up being too noisy or people
> don't like it, we can create another list.. but I figure that
> anyone working on the documentation ought to be kept abreast
> of what other people are doing to it. :-)
>
> More to come as it becomes available..

I don't think that it is proper to decide "hey, we should change this
about development" and propose it on a list with only a small subset of
developers on it.

I don't think it is a good idea to have cvs updates going to a
discussion list (after all, they don't go to new-httpd...), and I
don't think that it is a good idea to have them going where most
developers don't see them. That gives developers the idea that
they can just ignore docs entirely, which is not true at all.
Development and docs currently go hand in hand in a lot of areas.
That is the way it is because right now there simply aren't people
dedicated to looking at what code is written and then fixing the
docs as appropriate. While it is fine to have people doing more
stuff on the docs as they can, it shouldn't give developers the
idea that their responsibilities are lessened in any way. It has always
been a general rule of thumb that if you commit something that makes a
smallish change to how something works, you change the related docs.

The problem is that I haven't seen any proposal for or agreement of
exactly what you intend to change, just bits and pieces of it dropped here
and there. It seems that before anyone can agree to anything, they have
to know what it is...

Before you change anything, can you please send out a message saying
exactly what you want to change and give people a chance to read it and
respond before you do anything? Thanks.

Marc Slemko wrote:
>
> I don't think that it is proper to decide "hey, we should change this
> about development" and propose it on a list with only a small subset
> of developers on it.

Um, just *what* are you talking about? The doc extraction was
discussed on new-httpd and apache-core; this message to apache-docs
was to bring people interested in the docs project, but who *aren't*
developers, into the picture.

> I don't think it is a good idea to have cvs updates going to a
> discussion list (after all, they don't go to new-httpd...),

That's why I asked the question.

> and I don't think that it is a good idea to have them going where
> most developers don't see them.

If the developers care about the documentation, they can subscribe
to the list where the docco stuff goes.

> Development and docs currently go hand in hand in a lot of areas.
> That is the way it is because right now there simply aren't people
> dedicated to looking at what code is written and then fixing the
> docs as appropriate. While it is fine to have people doing more
> stuff on the docs as they can, it shouldn't give developers the
> idea that their responsibilities are lessened in any way. It
> has always been a general rule of thumb that if you commit
> something that makes a smallish change to how something works,
> you change the related docs.

So exactly what are you saying? That EVERYONE, doc worker or
developer, should be on new-httpd? And that docco CVS messages
should go to.. where?

> The problem is that I haven't seen any proposal for or agreement of
> exactly what you intend to change, just bits and pieces of it dropped
> here and there. It seems that before anyone can agree to anything,
> they have to know what it is...

I don't think you're reading your mail. I have proposed the exact
steps twice on new-httpd (where the discussion belongs as long
as the documentation is part of the code). And there have been
a bunch of people that have agreed to those steps, so it's hardly
fair to make that last statement.

> Before you change anything, can you please send out a message saying
> exactly what you want to change and give people a chance to read it
> and respond before you do anything?

I did that, but I'll do it again. When I mentioned it earlier
this week I said I wanted to get this done before the next
2.0 alpha.
--
#ken P-)}

Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>

On Fri, 21 Apr 2000, Rodent of Unusual Size wrote:

> Marc Slemko wrote:
> >
> > I don't think that it is proper to decide "hey, we should change this
> > about development" and propose it on a list with only a small subset
> > of developers on it.
>
> Um, just *what* are you talking about? The doc extraction was
> discussed on new-httpd and apache-core; this message to apache-docs

When was it discussed on apache-core? A year ago? Erm...

> was to bring people interested in the docs project, but who *aren't*
> developers, into the picture.

I'm afraid I am completely unable to find any reference to changing
it so commit messages for docs only go to apache-docs before this
message that you only sent to apache-docs.

> > I don't think it is a good idea to have cvs updates going to a
> > discussion list (after all, they don't go to new-httpd...),
>
> That's why I asked the question.
>
> > and I don't think that it is a good idea to have them going where
> > most developers don't see them.
>
> If the developers care about the documentation, they can subscribe
> to the list where the docco stuff goes.

You didn't give anyone who isn't subscribed to apache-docs a chance
to even participate in the discussion of where they should go!

> > Development and docs currently go hand in hand in a lot of areas.
> > That is the way it is because right now there simply aren't people
> > dedicated to looking at what code is written and then fixing the
> > docs as appropriate. While it is fine to have people doing more
> > stuff on the docs as they can, it shouldn't give developers the
> > idea that their responsibilities are lessened in any way. It
> > has always been a general rule of thumb that if you commit
> > something that makes a smallish change to how something works,
> > you change the related docs.
>
> So exactly what are you saying? That EVERYONE, doc worker or
> developer, should be on new-httpd? And that docco CVS messages
> should go to.. where?

I'm saying that the whole "docs tree is completely separate and
disjoint from the code" argument that you are trying to make is
bogus and is very bad for the project and for the docs themself.

The documents _are_ intrinsicly related to a particular code tree and
cvs commit messages for them should be sent to the same place that code
commit messages are. If you also want to add another list that gets
only doc commits, that's fine. But it is not ok to say that
devlopers have no obligation to care anything at all about docs.
That is not true and is quite destructive. Patches have been
rejected before until they have the proper doc updates with them,
and I think that is quite appropriate.

Your statement above "if developers care about the documentation" implies
that they have a choice to ignore the documentation. Last I was aware,
that was not true.

> > The problem is that I haven't seen any proposal for or agreement of
> > exactly what you intend to change, just bits and pieces of it dropped
> > here and there. It seems that before anyone can agree to anything,
> > they have to know what it is...
>
> I don't think you're reading your mail. I have proposed the exact
> steps twice on new-httpd (where the discussion belongs as long
> as the documentation is part of the code). And there have been
> a bunch of people that have agreed to those steps, so it's hardly
> fair to make that last statement.

I'm afraid I must have missed it. If you could forward me a copy of
the message that talked about moving commit messages to apache-docs I
would appreciate it... thanks.

>
> > Before you change anything, can you please send out a message saying
> > exactly what you want to change and give people a chance to read it
> > and respond before you do anything?
>
> I did that, but I'll do it again. When I mentioned it earlier
> this week I said I wanted to get this done before the next
> 2.0 alpha.

You are making up new steps as you go along, and it is clear that
exactly what should be done hasn't yet been thought out and is
being made up on the fly. I don't think it is worth trying to rush
it through before anyone understands what you are suggesting or
before you have even suggested everything you plan to do.

Marc Slemko wrote:
>
> I'm afraid I am completely unable to find any reference to changing
> it so commit messages for docs only go to apache-docs before this
> message that you only sent to apache-docs.

Oh, that's the part you meant. Yes, that message should
have been Cced to new-httpd. D'oh!

> > So exactly what are you saying? That EVERYONE, doc worker or
> > developer, should be on new-httpd? And that docco CVS messages
> > should go to.. where?
>
> I'm saying that the whole "docs tree is completely separate and
> disjoint from the code" argument that you are trying to make is
> bogus and is very bad for the project and for the docs themself.

I'm sorry that's how you've interpreted my remarks because
that's not their intent.
--
#ken P-)}

Ken Coar <http://Golux.Com/coar/>
Apache Software Foundation <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed" <http://ApacheUnleashed.Com/>

On Apr 21, Marc Slemko wrote:
> I'm saying that the whole "docs tree is completely separate and
> disjoint from the code" argument that you are trying to make is
> bogus and is very bad for the project and for the docs themself.

Not that I really want to step in the middle of this, but I do want
to point out that the PHP project has had great success with an
independent documentation project along the lines of what Ken is
proposing. There is a fairly significant number of people who are
focused on just making the docs better, and translating them into
other languages. (I believe there's translations into German,
Japanese, and Italian underway. I'm not sure about the last, and
there may also be others.)

I do also see tremendous value in commits to the documentation and
the code trees going to the same list, which should be seperate
from the discussion lists. I think it would help keep both groups
(assuming they aren't completely overlapping sets of people) in
communication. (Not that I'm suggesting it replace real communcation,
or that the developers of code should be absolved of any responsibility
for writing documentation.)

Jim