• DevSummit
• 201105
• Documentation

FreeBSD Developer Summit Documentation Working Group

May 11th (Wednesday), 09:00-12:00, SMD room 428

Overview

As part of the May 2011 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.

Note: We will try to set up videoconferencing (BigBlueButton, Skype, etc.) for interested folks who cannot attend the DevSummit in person, but who would like to participate nevertheless. If you are interested in this, get in contact with either one of the session chair persons below and provide your time zone and topic of interest.

Goals

• Brainstorming about a plan and time schedule for infrastructural changes.
• 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.

Specific Topics

1. Doc Format/Toolchain (10+60min)

Discuss improving toolchains and contents of our documentation set

We are currently using a mixture of SGML, XML, and wiki for our documents. Although most of us recognize they are really complex and should be sorted out in a consistent way, possible future directions are still unclear. We need to share our problems in a more specific manner, especially on the following three fronts:

• difficulties for document writing,
• ones for maintaining the existing documents, and
• reusing the documents.

For getting substantial progress, the following should be discussed:

• 1-a) Problems we have now. "Complex" itself is not always bad if it works for our purpose. Steepness of the learning curve in SGML/XML/DSSSL/XSLT might be a negative factor.
  1-b) What we need, and what the technologies provide. Although a specific toolchain/markup language provide many things, they often cause people who are unfamiliar with them trouble.
  1-c) Discussion on infrastructure including our repository, web service, and wiki.

2. Contents (10+60min)

Our document set contains old information and needs to be updated and/or reorganized. This kind of discussions appeared again and again, but if we need a large change to the existing contents we need a road map including how, when, and who.

• 2-a) Do we have specific ideas for the update/reorg? Some are in the DocIdeaList page.
  2-b) Do we have specific ideas for new contents? Some are in the DocIdeaList page.
  2-c) Our content management needs a concept of "life cycle" for a content. We can remove aged documents but we have no procedure for the removal. Some defined actions (reevaluation of docs at a certain moment after added, for example) should be established. For this goal, probably we need some sort of classifications of documents we maintain first. We have www pages, Handbook, articles, FAQ, release related docs, wiki, manual pages, etc. now. They can be classified by its updating frequency, nature of the contents, possibility of reuse, etc. These classifications are also important for what kind of toolchain/format we need; news items should be maintained in a form of a database, not in a single lengthy HTML file, for example.
  2-d) Translation. Keeping the translated documents up-to-date is really difficult. How do we handle this kind of problems? How much amount of translations do we have?

Discussion for improving the current document set by creating new contents and/or services would be useful. Random ideas are as follows:

• 2-e) A portal page per port/subsystem/device driver with an embedded forum and/or wiki. While FreeBSD consists of a large number of components, all of discussions and information are scattered over separate mailing-lists, GNATS database, www pages, forums, or wiki pages. A one-stop page for a specific component which aggregates the scattered information would be helpful to improve this situation. This kind of text processing can be designed by using XML + the existing information infrastructure such as mailing-lists.
  2-f) Can we have more announcement/PR channels in a consistent way? We still rely on mailing-lists and there is no handy way for the developers/projects to make an announcement other than news.xml. Periodic status reports are a success on this front. Discussing how to write/edit/send out/archive such a document would be useful because it is a field that doc committers should give other committers help. A portal page described in 2-e) should be effective, too.
  

3. Other submitted ideas and future plans (40min)

Review and discuss items in the DocIdeaList page.

Attendees

Results

Picture of notes on the blackboard