FreeBSD Developer Summit Documentation Working Group
May 9th (Wednesday), DMS 3102.
Overview
As part of the May 2012 FreeBSD developer summit, this working group will focus on the FreeBSD documentation. This is a by-invitation event open to developer summit attendees interested in this topic. If you have a topic that you want to discuss at the Working Group, get in touch with the session chairs.
Note: We will try to set up videoconferencing (Skype, etc.) for interested folks who cannot attend the DevSummit in person, but who would like to participate in virtual form. If you are interested in this, get in contact with either one of the session chairs below and provide your time zone and topic of interest.
Goals
- Brainstorming about a plan, time schedule and work left to do for infrastructural changes like the repository conversion to SVN.
- Discuss classification of our documentations and maintenance policy. Plus, discuss what toolchains/formats we can use for our goals.
Review and discuss updating contents and submitted items in the DocIdeaList.
Note:
We encourage working group attendees to also attend the Collaborative Docsummit between BSDCan/PGCon, where documentation ideas can be shared between BSD and Postgres people. If you can make it, please register separately for this event.
Specific Topics
Overall, we want to focus in this working group on the things that are still open from last year. Specifically, we thought about the following agenda:
CVS doc repository conversion: by the time this session starts, we'll have roughly 1 month of experience since the conversion of the SVN repo on April 7, 2012 (HEADS UP message on freebsd-doc mailinglist). We will report on our experiences, discuss open issues and further steps from there.
XML DocBook conversion: we agreed at EuroBSDcon2011 to do the SVN repository conversion first. Now that this has been mostly done, we want to discuss what we can do to move this conversion forward. For example, we might want to update/replace our SGML primer for DocBook XML.
- Handbook print and electronic editions: There is still demand from various parties (FreeBSD Mall, iXsystems) to publish a newer version of the handbook. We wanted to do this in 2011, but things got in the way. On the plus side, we have made great progress in some areas due to Google Code-In participation. Discuss what needs to be done, distribute the work and get moving is the goal for this topic.
Doc tools: Tools like igor have become popular recently and we would like to encourage attendees to use and probably extend it. WarrenBlock will briefly show and discuss what this tool and others can do to help doc committers. Collecting more ideas for tools that we could use/create and distribute the work to make them available is one goal.
- Doc summit: we had rough ideas to hold a separate, doc-only summit to get the handbook ready for publishing. Benedict had some plans of either organizing such a thing himself or at least help with planning. Getting opinions on this idea and making a list of people who are interested in participating is one goal of this item.
Review and discuss items in the DocIdeaList page.
Attendees
Name |
Affiliation |
Topics of Interest |
Other Notes |
|
|
Session chair (1/2) |
|
FreeBSD Project |
Handbook, reorganization/consolidation, tools and infrastructure |
Session chair (1/2) |
|
FreeBSD Project |
|
will give a short presentation about igor (automated proofreader for documentation) |
|
FreeBSD Project |
|
|
|
FreeBSD Project |
|
|
|
FreeBSD Project |
|
|
|
|
|
|
|
FreeBSD Project |
* |
|
|
David Chisnall |
|
|
|
Michael Dexter |
|
|
Notes
Session notes will be recorded in this etherpad document: http://openetherpad.org/olGW4r5GcF