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-...@lists.debian.org . Actual contents are managed by CVS at :ext:usern...@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-...@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-b...@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://$use...@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-...@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 -- To UNSUBSCRIBE, email to debian-project-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/20121201025705.GC8914@goofy.localdomain