Note: Do not edit this page yourself unless asked to.

FreeBSD Developer Summit: Documentation Working Group

Friday, 19 October 2012, 9:00 - 12:30 (with a half hour break in between)

Overview

This working group mainly focuses on trying to pick up what was left from the session at BSDCan's DevSummit and the combined BSDCan/PGCon doc summit and continue what actions and solutions have been identified there as well as new things that came up in the meantime.

If you would like to participate, contact the working group chairs below and CC devsummit@. You will be then added to this page. Please include a list of things you want to talk about or the areas you are interested in. This helps us in planning the session and to bring people together with common interests.

It is possible to bring in people who cannot attend in person via video conference or chat tools. Notes during the session will be published later on for the whole community to see what we discussed.

Goals

In particular, we would like to cover the following topics. This is not an exhaustive list and if you feel there is something missing that you want to talk about, contact one of the session chairs and we will include your topic here. Note that the numbering of the topics does not represent an ordering or importance indication of any kind, but rather a reference to the second table with the "topic of interest" column.

Topics

#

Topic Description

XML DocBook conversion

It is either already there by the time EuroBSDcon happens or the conversion is still ongoing. Either way, it should be discussed what is left to do, like updates to the FDP primer and training of our doc committers to the new doc infrastructure based on XML. We also have to think about depending on Java since the best free PDF renderer out is based on Java.

Handbook print and electronic editions

Now that there is SVN with support for branches, the reorganization of the handbook into a publishable format (including but not limited to: the preface with all the changes since the last publicized version) could be started. Discuss what is the best format to do this and how to divide the work among those who are interested in seeing this happen. Also, e-book readers should be well supported.

Doc tools

Tools for documentation work, little helper scripts (like one for comparing revisions between translation projects and the en_US repo tree) should be talked about. Collecting more ideas for tools that we could create/use and distribute the work to make them available is one goal. Maybe is there any way we can have a customized IDE like Eclipse for easier document authoring?

Old content

We should deal efficiently with old content. Wrong information is worse than no information at all. Possible ways of detecting outdated content and possible ways of marking outdated translations as such.

UTF-8 encoding

We could achieve more uniformity by using UTF-8 all over the tree. Toolchain support and possible difficulties should be evaluated carefully before such a migration (e.g. editing docs in a terminal).

Best practices

There are quite some non-standard ad-hoc scripts that generate pages. XSLT is based on templates (less error-prone and extensible) and nicely fits our XML infrastructure. Web pages contain scattered formatting elements and attributes, which should be ideally done globally by CSS. XHTML 1.0 Strict or a bit more constrained schema would avoid this. Document these and similar best practices in the FDP primer and assure it covers everything either by itself or by proper pointers.

Profiling of Handbook

It is a constant problem that the base system changes and we have scattered information that only applies to older versions. Newer version of DocBook provide a feature - called profiling - that allows us to mark up specific parts as belonging only to one profile. We could thus mark up such parts and generate release-specific parts of Handbook or still generate the whole one. Such markup would also help us locating outdated parts when a major release reaches EOL.

Note: General presentations about work you have done that does not require further discussions should be submitted for the FreeBSD Developer Summit track at EuroBSDcon (see general developer summit page).

Attending

In order to attend you need register for the developer summit as well as by email for the session and be confirmed by the working group organizer. Follow the guidelines described on the main page or what you received by email. For questions or if in doubt ask the session chairs.

Everyone interested in documentation is welcome to join. This includes doc committers and contributors, but we have also learned in the last sessions that sometimes ports, src and even infrastructure people can provide valuable insights into problems the doc people scratch their heads about far longer than necessary. So a mixed audience is welcome, but we will also try to keep the number of attendees small enough to be productive.

Please do NOT add yourself here. Your name will appear automatically once you received the confirmation email. You need to put your name on the general developer summit attendees list though.

#

Name

Username / Affiliation

Topics of Interest

Notes

1

DruLavigne

dru

chair

2

BenedictReuschling

bcr

chair

3

GáborKövesdán

gabor

4

ReneLadan

rene

5

MichaelDexter

CallForTesting.org

6

GavinAtkinson

gavin

7

TodMcQuillin

spamcop.net

Notes

http://openetherpad.org/Ybnfab21nI

Results

201210DevSummit/Documentation (last edited 2012-10-20 10:26:30 by BenedictReuschling)