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

Re: How to help debian-doc



Hi,

Let's keep this in public so others can benefit.

Short answer is "There is no rule how does one contribute new document
... it is just like the case for new software packages.  It's
do-ocracy."

See http://upsilon.cc/~zack/talks/2011/20110321-taipei.pdf

For changes, find and contact proper ML or BTS.

Let me elaborate more ...

On Sun, Aug 25, 2013 at 03:19:15PM -0500, Robert W. Oliver II wrote:
> Hi Osamu,
> 
> Thank you for your reply.  I spent about an hour going through the Debian

Sorry, but it looks to me that it was not enough time to read key docs
linked from it.  It is huge site to get an idea.  For example, please
read at least:
 * http://www.debian.org/doc/manuals/debian-faq/
 * http://www.debian.org/doc/manuals/maint-guide/index.en.html
 * http://www.debian.org/doc/manuals/debian-reference/
 * and all the site I mentioned in the previous mail.

(I do not even remember all these.  I use google to find some info
within our site.  You should do the same.  I am writing in my foreign
language and it is taking some good time to respond to you.)

> site, but I think a lot of the documentation for new documents is quite
> confusing.  Perhaps this is an area that can be improved on?

There are many things to be improved as always but your comment is too
vague for me to answer specifically.  (If you are talking about web page
organization, this ML may not be the right path.  There is a list for
web page.)

> What I'm specifically wondering, other than the wiki - how does one
> contribute a new document or changes to one?  Is that done through a
> sponsor?  If so, are there any mentors willing to sponsor a new documenter?

For my case, I created "Debian Reference" by myself and published under
the license compatible with Debian elsewhere on the web.  I was invited
by DD and asked to make package.  I did and he sponsored it to the
archive and put it to the Debian Site.

Before that (and also after that), there were many attempts to put
skeleton of document and expected "OTHERS" to finish.  Those ended up
UNFINISHED works.

Please read "Chapter 1. Getting started The Right Way" of "Debian New
Maintainers' Guide".
  http://www.debian.org/doc/manuals/maint-guide/index.en.html

This gives you idea how this kind of organization work. No body handhold
me to learn.  It was tough but I did it by myself.  Since we are
volunteer organization, we tend to be resource stretched.  Your
contribution should be interesting enough for others to feel like
spending time on it.

These days, if you have many wiki pages, then making full doc may be an
idea only as the next step.  There is no reason to make another
unmaintained half-done doc as regular web pages.

Besides, you seem to have pretty good presence on the web. You can
create a site publishing documentation if that is what you want to do.
Once they are done, let us know.  If you wish to fix/correct things
already on our web site, please file bug report or communicate via
proper mailing lists.

Oh, if you have idea to improve our web page, I think you should make
proof-of-concept pages and discuss with people managing web pages.  When
you do that, I strongly recommend you to understand how our pages are
translated and published to many mirrors.  (This is not small private
web pages on a single server.  They are documented somewhere on the web
and some VCS repo.)

Osamu


Reply to: