Projects List (was Re: Doc BoF at EuroBSDCon)

[Murray Stokely]

On Fri, Dec 03, 2004 at 04:57:04PM -0500, Tom Rhodes wrote:
> Post a list of tasks of mixed sizes,
> Request people (people, not committers not contributors) to grab a task,
> Commit completed work after some minor/major review,
> As one task is completed another is grabbed up.

Thanks for pointing out to me the page :

  http://wiki.daemon.li/index.pl?DocIdeaList

We should probably link to that from the current.sgml file.

There are a few nice todo lists items there.

Here are some others I recently added to the current projects page
that I'd love for people to help out with :

1. Improve Handbook Index
2. Modernize website with CSS
3. Contribute Advocacy Slides/Presentations

We already have a mechanism for listing projects that we'd like for
people to help out with.  It's great that we also have a Wiki now, but
we should point to that from our official pages in www/en/docproj.  At
the moment, I prefer the Wiki to completement but not to replace
current.sgml.

   - Murray

---

1. Improve Handbook Index

Responsible: FreeBSD-doc <FreeBSD-doc at FreeBSD.org>

Synopsis: Many new sections have been added to the FreeBSD Handbook
without index terms, others have been added under inappropriate
primary or secondary indexterms that do not fit the existing
scheme. Some indexterms have been added inside list items or other
areas where they are not allowed by our stylesheets, causing '???' to
be printed in the index instead of a real page number.

Index work requires experience and anyone who works on this task is
highly encouraged to carefully read through the existing
(print-output) index, and to have read the Chicago Manual of Style or
other style books that deal with indexing. Please see the CVS history
of some of the chapter.sgml files to see some of the indexing errors
that have been corrected in the past. It is imperative to view the
PostScript version of the Handbook after making any changes to
indexterms as many errors, such as long words or deeply nested
indexterms will break the two column output there, or cause the page
number to be listed as '???'.

There is a script doc/share/misc/indexreport.pl which can be used to
find areas of an SGML file where <indexterms> are sparse.

---

2. Modernize website with CSS

Responsible: FreeBSD-www <FreeBSD-www at FreeBSD.org>

Synopsis: Most of the FreeBSD.org website is written in HTML 3.2. Some
of the files have been updated to technically use the HTML 4 DTD, but
in spirit they are still HTML 3.2 files with very minimal use of CSS
and extensive use of hardcoded presentation tags.

Any redesign of the FreeBSD.org website will be more CSS based. Moving
existing pages to CSS allows us to more quickly modify the look and
feel of the entire website and should preserve bandwidth. As with
DocBook for our technical documentation, recent CSS and HTML standards
allow us to separate presentation from data and we should be taking
better advantage of this with our website.

---

3. Contribute Advocacy Slides/Presentations

Responsible: FreeBSD-doc <FreeBSD-doc at FreeBSD.org>, Murray Stokely
<murray at FreeBSD.org>

Synopsis: Presentations marked up in the DocBook-slides DTD have
recently been added to the documentation set in
doc/en_US.ISO8859-1/slides. More advocacy content is needed, and
additional stylesheet work is needed to pull in content from the
release notes and other XML content in our documentation set to build
up-to-date slides with 'make'. A simple example presentation was
committed with some of this functionality, but there is more work to
be done! Also, the stylesheets for print/PDF output (using the Java
based XSLT processors, PassiveTeX is too limiting for slides) could be
improved as the default DocBook Slides XSL-FO stylesheets produce very
spartan slides.