Gentoo Archives: gentoo-dev

From: Sven Vermeulen <swift@g.o>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] GDP: Mid-year status update
Date: Fri, 10 Jun 2005 18:03:59
1 Hi all,
3 In the beginning of the year, I have posted the "New Year Goals" for the
4 Gentoo Documentation Project [1], listing a few bigger topics we would like
5 to address in this year.
7 Now that we are half-way, I would like to inform you about the progress the
8 GDP has made since then. For your reference, you can find the New Year Goals
9 in the GDP Status Update, dated March 7th [2], but I will relist them here
10 with information on their advancements.
12 ** Pull in developers/contributors
14 Before randomly starting to pull in users who want to join the GDP, we
15 have crafted a guideline on how we recruit developers [3]. This guideline
16 includes numbers on how we (Xavier and I) look at contributors before we
17 deem them active enough to be part of the project. It also includes a Quiz
18 that each contributor has to fill in succesfully.
20 With this guideline in place, we have already invited a few contributors
21 to join the GDP crew. Some of them are lead translators, non-x86
22 architectural documentation developers (MIPS, AMD64, PPC) and others are
23 English Documentation Editors and reviewers.
25 Others are in the pipeline for joining.
27 We are however still looking for internal developers who want to join the
28 GDP team to help their project deliver quality documentation. Internal,
29 because they need to have a good knowledge of the project in their hands.
30 This is however no hard-written rule: if you are known to the project but
31 no Gentoo developer, that is of course good as well, but we do want the
32 acknowledgement from the project.
34 ** Reintroduce Status Updates
36 Until this day I have not reintroduced status updates (the request on all
37 documentation editors to submit personal status updates) since the team is
38 currently working well (we have a good bug squashing rithm) and there is
39 no direct need to duplicate what we already know of each other on the
40 mailinglist.
42 However, when the project would become too large to handle directly,
43 indirect status updates will be introduced.
45 But again, for the time being, this has not been found necessary.
47 ** Improve documentation on GuideXML
49 The idea here was to document the use of the various tags better (/why/ do
50 we have an <abstract> tag, where is it used, etc.). With the Quiz in mind,
51 this has been put back a bit as the Quiz directly asks each contributor
52 for all this information.
54 Putting it all in a single document would defeat the idea of the quiz a
55 bit (since every body would be able to copy/paste everything).
57 ** "Writing Style" documentation
59 The entire Gentoo Documentation Repository is written by various
60 individuals. This gives a cluttered idea on the writing style involved in
61 the documents. We have not received any (negative) feedback about this,
62 but we do feel that some common writing styles should be introduced.
64 There is no proposal on a writing style yet, though, so see this as still
65 being "Planned".
67 ** Define Location of Documentation
69 Most projects put project-specific documentation on their project page.
70 For the GDP, as long as this documentation does not affect the broad user
71 base, this is just fine. Projects should know however that this
72 documentation is less likely to be reviewed by the GDP or translated.
74 Whenever a document can be of interest for a larger population, we feel
75 that the document must reside under, which is
76 the GDPs play ground. Not only does this improve the quality of the
77 documentation, but it also improves the visibility of the document to the
78 wider audience.
80 ** Audit the Existing Documentation
82 Auditing is of course a work that's always in progress. We have recently
83 decided to rewrite the ALSA Guide [4] as it was getting too cluttered with
84 patches here and there to fix things that are obsoleted or renewed.
86 Other documentation is being audited or worked on. If you find anything
87 outdated or in need of an update, bug [5] us.
89 ** More USE-case Documentation
91 With USE-case documentation we mean documents that cover multiple
92 subjects simultaneously. Documents such as the LDAP Howto [6], the UTF-8
93 Guide [7], Mailfilter Guide [8] and others are good examples.
95 Such documents contain information that is more difficult to find
96 elsewhere. However, we have seen that the community appreciates the
97 configuration guides (Xorg, KDE, GNOME, fluxbox, ...) a lot as they are
98 frequently referenced in #gentoo, on the mailinglists and on the Gentoo
99 Forums, so the urge to go for USE-case documentation has decreased a bit
100 in favor of the latter.
104 If you have questions about other activities within the Gentoo Documentation
105 Project, proposals or feedback, do not hesitate to reply or contact me
106 personally at swift@g.o or SwifT on
108 Wkr,
109 Sven Vermeulen
111 [1]
112 [2]
113 [3]
114 [4]
115 [5]
116 [6]
117 [7]
118 [8]
120 --
121 Documentation project leader - Gentoo Foundation Trustee
123 The Gentoo Project <<< >>>