Re: Opinion on Debian documentation
Hi,
On Wed, Nov 28, 2012 at 08:25:17PM +0200, Alexandru Vochescu wrote:
> Hi,
>
> I am working at a task at google code-in where i have to
> write about "documentation structure of other projects". I chose to
> write about Debian, because i'm used to Debian (I have Debian Sid). And
> this task also says "plus finding a way of determining the project's
> opinion of their documentation (a docs@ mailinglist might be a good
> start)" , so , can you tell me what's your opinion of Debian
> documentation? ( I would apreciate very much if you can reply me in less
> then a day .
This is not a good way to do good research :-) Too rush ...
> That's my deadline for the task). Link to the task:
> http://www.google-melange.com/gci/task/view/google/gci2012/7953209 .
Maybe too late but FYI
========== Short answer ==========
We use mostly static web pages generated from the source written in some
mark-up languages (DocBook XML and webwml) as the way to document
things. This gives very solid ground for translation and scalability
via mirroring. (This is not very flexible, ...)
We also supplement this with wiki and announcement mailing list (with
its web archive) to address more trangent and fast moving needs for
documentation.
========== Long answer ===========
Debian related documentation can be found in several sources:
1. Debian packages
Released official documents are packages as Debian packages just like
other software. debian-policy contains the most essential policy while
developers-reference contains best practices. Write access is limited
to the maintainer but updates of their contents can be requested via
Debian BTS system http://www.debian.org/Bugs/ .
Also, each released software package contains
/usr/share/doc/README.Debian where debian specific documentation
specific to the package.
2. Debian web site
This is the pages accessible as www.debian.org and mostly managed by
people discussing on debian-www@lists.debian.org . Actual contents are
managed by CVS at :ext:username@cvs.debian.org:/cvs/webwml as explained
http://www.debian.org/devel/website/using_cvs
These are static web pages generated by webwml. Most translation using
PO system to keep them in sync. Its write access is limited to alioth
webwml member : https://alioth.debian.org/projects/webwml/
3. Debian doc
This is the sub-project of Debian to support Debian specific
documentation. The page at http://www.debian.org/doc/ can be considered
as its front page. It uses debian-doc@lists.debian.org as primary
communication channel. Its sources are located in subversion repository
at svn+ssh://svn.debian.org/svn/ddp/manuals/trunk . Its write access is
limited to alioth ddp member : https://alioth.debian.org/projects/ddp
(The source of debian-policy, developers-reference, release notes, and
FAQ are hosted here.)
VCS contents tends to be a bit ahead of released packages and is
published as generated web page under http://www.debian.org/doc/manuals/
Most of these documentation uses DocBook XML (Some still use
Debiandoc-sgml which is an extended linux-doc).
4. Debian installer documentation
The debian-boot@lists.debian.org mailing list is the main forum for
discussion and work on Debian-Installer. These people also produce its
installer documentation. This source is hosted withing Debian installer at
svn+ssh://$userid@svn.debian.org/svn/d-i/trunk .
Its generated pages can be seen
http://www.debian.org/releases/testing/installmanual
If I remember correctly, the source of documentation uses DocBook XML.
5. Debian wiki
This is the pages accessible as wiki.debian.org and managed by
some people on debian-www@lists.debian.org . Actual contents are
contributed by almost anyone who register themselves with their email
address. Its back-end is MoinMoin.
6. Debian mailing list archive
Especially http://lists.debian.org/devel.html#debian-devel-announce
This contain essential documentation in plain text.
Basically, all these are adopted by the immediate needs, technical
feasibility, and availability via do-ocracy.
Good luck,
Osamu
Reply to: