[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Documentation for new maintainers



[Two in one here]

In article <E0zZM8r-0006Dj-00@resnet216-96.resnet.buffalo.edu>, "Buddha M.D. Buck" <bmbuck@acsu.buffalo.edu> writes:
> I don't think it's really a wasted effort.  There is a lot of
> information there, most of it is FAQ-material.  Probably half of the
> questions asked in debian-mentors could be answered by it.  Spread
> out all over the place makes it hard to find.  I know that -I- would
> be helped by it.

Well, sure.  But creating new documents is going to spread it out more.

I suggest (a) volunteer to help the FAQ-O-Matic
          (b) volunteer to help with the new install doco for slink
          (c) join <debian-doc@lists.debian.org> and ask how you can help
          (d) check out DDP - http://www.debian.org/~elphick/ddp/index.html

In article <199811021338.OAA04417@ezili.sis.pasteur.fr>, Stephane Bortzmeyer <bortzmeyer@pasteur.fr> writes:
> On Friday 30 October 1998, at 20 h 52, the keyboard of Raphael
> Hertzog <rhertzog@hrnet.fr> wrote:

>> as we speak about new-maintainers problems, I think a document
>> intented for them could be helpful. I'll write something as soon as
>> I can.

> Good idea. As several people mentioned there *are* documents but
> most of them are out of date and the maintainers does not seem very
> reactive (overloaded, fed up, I don't know).

Well, someone is gung ho today, but will the be around in 2 years?
No?  Then we have more stale, unmaintained documentation.

Documentation is a process, not a product.  You have to build
consensus and work on something that other people will help you on,
and read, and contribute to.

> It clearly a dark area of the Debian project.

I agree, although I would say that there's a general problem of Free
documentation.  Can hackers document well?

> The maintainers feel under attack when there is a criticism about it
> but it's true.

Well, the most frustrating thing is (a) complaints with no action, or
(b) claims that someone is going to write something then no delivery
(I'm as guilty here as the next)

> I would advise new developers to do not trust documents in
> <http://www.debian.org/devel/> apart from the Policy Manual and the
> Developers Reference. Most of them should be removed from the
> Developer's Corner.

Go to the DDP pages.  Adopt a document!  Learn CVS and SGML; hell, it
might land you a job in "document engineering" while you're at it.

BTW, IMHO, the best place to start for new maintainer documentation
might be Jaldhar H. Vyas's rather aborted but nice effort (but in
HTML, blech) at http://va.debian.org/~jaldhar/.

--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>


Reply to: