[gentoo-dev] GDP: Mid-year status update

[Sven Vermeulen]

Hi all,

In the beginning of the year, I have posted the "New Year Goals" for the
Gentoo Documentation Project [1], listing a few bigger topics we would like
to address in this year.

Now that we are half-way, I would like to inform you about the progress the
GDP has made since then. For your reference, you can find the New Year Goals
in the GDP Status Update, dated March 7th [2], but I will relist them here
with information on their advancements.

** Pull in developers/contributors

  Before randomly starting to pull in users who want to join the GDP, we
  have crafted a guideline on how we recruit developers [3]. This guideline
  includes numbers on how we (Xavier and I) look at contributors before we
  deem them active enough to be part of the project. It also includes a Quiz
  that each contributor has to fill in succesfully.

  With this guideline in place, we have already invited a few contributors
  to join the GDP crew. Some of them are lead translators, non-x86
  architectural documentation developers (MIPS, AMD64, PPC) and others are
  English Documentation Editors and reviewers.

  Others are in the pipeline for joining.

  We are however still looking for internal developers who want to join the
  GDP team to help their project deliver quality documentation. Internal,
  because they need to have a good knowledge of the project in their hands.
  This is however no hard-written rule: if you are known to the project but
  no Gentoo developer, that is of course good as well, but we do want the
  acknowledgement from the project.

** Reintroduce Status Updates

  Until this day I have not reintroduced status updates (the request on all
  documentation editors to submit personal status updates) since the team is
  currently working well (we have a good bug squashing rithm) and there is
  no direct need to duplicate what we already know of each other on the
  mailinglist.

  However, when the project would become too large to handle directly,
  indirect status updates will be introduced. 

  But again, for the time being, this has not been found necessary.

** Improve documentation on GuideXML

  The idea here was to document the use of the various tags better (/why/ do
  we have an <abstract> tag, where is it used, etc.). With the Quiz in mind,
  this has been put back a bit as the Quiz directly asks each contributor
  for all this information.

  Putting it all in a single document would defeat the idea of the quiz a
  bit (since every body would be able to copy/paste everything). 

** "Writing Style" documentation

  The entire Gentoo Documentation Repository is written by various
  individuals. This gives a cluttered idea on the writing style involved in
  the documents. We have not received any (negative) feedback about this,
  but we do feel that some common writing styles should be introduced.

  There is no proposal on a writing style yet, though, so see this as still
  being "Planned".

** Define Location of Documentation

  Most projects put project-specific documentation on their project page.
  For the GDP, as long as this documentation does not affect the broad user
  base, this is just fine. Projects should know however that this
  documentation is less likely to be reviewed by the GDP or translated.

  Whenever a document can be of interest for a larger population, we feel
  that the document must reside under http://www.gentoo.org/doc/en, which is
  the GDPs play ground. Not only does this improve the quality of the
  documentation, but it also improves the visibility of the document to the
  wider audience.

** Audit the Existing Documentation

  Auditing is of course a work that's always in progress. We have recently
  decided to rewrite the ALSA Guide [4] as it was getting too cluttered with
  patches here and there to fix things that are obsoleted or renewed. 

  Other documentation is being audited or worked on. If you find anything
  outdated or in need of an update, bug [5] us.

** More USE-case Documentation

  With USE-case documentation we mean documents that cover multiple
  subjects simultaneously. Documents such as the LDAP Howto [6], the UTF-8
  Guide [7], Mailfilter Guide [8] and others are good examples.

  Such documents contain information that is more difficult to find
  elsewhere. However, we have seen that the community appreciates the
  configuration guides (Xorg, KDE, GNOME, fluxbox, ...) a lot as they are
  frequently referenced in #gentoo, on the mailinglists and on the Gentoo
  Forums, so the urge to go for USE-case documentation has decreased a bit
  in favor of the latter.



If you have questions about other activities within the Gentoo Documentation
Project, proposals or feedback, do not hesitate to reply or contact me
personally at swift@g.o or SwifT on irc.freenode.net.

Wkr,
      Sven Vermeulen

[1] http://www.gentoo.org/proj/en/gdp
[2] http://www.gentoo.org/proj/en/gdp/status/status_20050307.xml
[3] http://www.gentoo.org/proj/en/gdp/doc/doc-policy.xml#doc_chap4
[4] http://www.gentoo.org/doc/en/alsa-guide.xml
[5] http://bugs.gentoo.org
[6] http://www.gentoo.org/doc/en/ldap-howto.xml
[7] http://www.gentoo.org/doc/en/utf-8.xml
[8] http://www.gentoo.org/doc/en/mailfilter-guide.xml

-- 
  Documentation project leader - Gentoo Foundation Trustee

  The Gentoo Project   <<< http://www.gentoo.org >>>