httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marc Slemko <>
Subject Re: Docco update messages
Date Fri, 21 Apr 2000 16:10:16 GMT
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.

View raw message