FreeBSD Developer Summit: Documentation

May 16, 2013 13:30-16:30 in MRT 256

Overview

This working group will focus on the FreeBSD documentation, it is generally open to people with an interest in documentation work, as well as src and ports people. 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

1

Handbook print edition (status of ongoing work, what needs to be done, how to involve more people, etc.)

2

Website redesign (we talked about this in the past, but will revisit it now for possible development in a SVN branch, collect ideas for website features)

3

Infrastructural changes (DocBook XML changes mostly, might connect to website redesign item)

4

Recruiting new doc committers/contributors (we need more people to help maintain our documents/website, find mentors, possible candidates, new strategies to involve people)

5

Helping our translation projects keeping up with changes (ties into the previous item and also possibly the handbook print edition if we want translated versions, finding tools that can help, compare to how PC-BSD is doing it)

6

Separate doc hackathon (planning, who might be interested in this, time/date, format, location)

7

Give postmaster@ the permission/training to maintain mailing list entries in the handbook by themselves. At the moment, they need to open a doc PR and a doc committer needs to make the changes, for example, when a new mailing list is created.

8

Give a few members (portmgr perhaps?) of ports the ability to make changes in the porters handbook without going through an extensive cycle between doc and ports people. A policy needs to be fleshed out to determine boundaries and permissions.

9

Quality assurance (link checkers, automated igor runs that displays errors on a website)

Note: General presentations about work you have done that does not require further discussions should be submitted for the FreeBSD Developer Summit track at BSDCan (see the 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.

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

DruLavigne

dru

*

Session chair

BenedictReuschling

bcr

*

Session chair

MichaelLucas

mwlucas

MichaelDexter

CallforTesting.org

Allan Jude

Scale Engine

EitanAdler

eadler

 

GlenBarber

gjb

 

WarrenBlock

wblock

TomRhodes

trhodes

Notes

The notes for this section are here: http://openetherpad.org/BSDCAN2013DocWG

/!\ Since openetherpad is not available at the moment, here are the notes from the group that I still had open in a browser tab:

Welcome to BSDCan 2013 DevSummit Doc Working Group

ISBN_1-57176-407-0/ repo

Todo list as of first round of edits: http://openetherpad.org/R6vMaCQ1GI

ToDo List for the print edition of the handbook: https://wiki.freebsd.org/PublishedFormats

We need to tap specific developers on the shoulders to get info needed for missing content--asking for general help on a mailing list won't cut it

It's content we need, doc team can take care of markup/formatting/editing

Docbook editors:

https://help.ubuntu.com/community/DocBookEditors

Useful for doc member to give the dev an outline of content and have the dev fill in the details

I actually think that a way to do this is:

1) Have a list of things we need to know. There ought to be a common outline type for how we write a section. Much like a newspaper story has an underlying format.

2) Ask for backup documents. Some folks really do write these.

3) Identify the correct developer and as for a few paragraphs and let them know that you want to continue to ask questions. 201305DevSummit

201305DevSummit svn allows merges both ways (cherry quick revisions using reintegrate)--this needs to be checked

https://wiki.freebsd.org/ThwackAFAQ

Editorial choices are the choice of the doc team, however, edits which inadvertantly break technical meaning need to be reverted/fixed

If there is a need for the keys in a book format, create a separate PDF which is available for print on demand for the users who desire it. Do we really need them in the print edition? Room concensus seems to be "no".

Doc team should approach core first to give a heads up that Handbook is undergoing major changes and if core could back doc team for edits which do not affect technical accuracy.

Wiki updated to add possible names next to new content required - both people who have offered to write, and people who may be good contacts but haven't volunteered themselves.

David Chisnall volunteered to put people interested in writing FreeBSD-related books in contact with publishers specialising low-volume print runs.

Web redesign

Need links to forums, twitter etc. Ports seem to be an afterthought. Better links to downloads, including embedded downloads. Links on the front page should go into intermediate pages, not into technical detail.

Search box - We need to fix this. Duck Duck Go? Google? Google Search and both Analytics/Webmaster etc are separate - we'd gain nothing in that regard using Google.

Could configure varnish to send a % of users to a new version of website for feedback

New website design could be in a separate branch; needs a small team dedicated to a new design and incorporating user feedback e.g. Gavin, Isabel, There are good notes from last year's Cambridge summit on ideas to incorporate into the design. Content and layout are separate issues.

DuckDuckGo (big FreeBSD user) has an API for non-tracked search (to not have to resort to Google), also a good Press Release opportunity

(Isabell is very keen to not shudder when visiting FreeBSD.org, and would love to help with a redesign.)

Other Search Ideas:

http://www.elasticsearch.org/ - Can index anything not just web pages

Recruiting

Option on each handbook page to add notes? User wiki? Can we get back the footer indicating the source file? We should find, and recommend, a Docbook/XML editor Source committers still don't know they can give plaintext to a doc person to have it XMLified

A way to find who did what to whom and when.

http://www.ohloh.net/p/freebsd

Not perfect but can be a good start. Also the Foundation is looking at extracting data from this to figure out who is working on FreeBSD. It's something the Linux folks report each year for their tree.

Translation

PC-BSD use Pootle (textproc/pootle) to assist translators. Could we actually share effort with PC-BSD?

Misc

Doc hackathon. Cambridge hackathon happening, end of August.

Results

(Add a list or attach slides detailing the achieved results here.)

201305DevSummit/Documentation (last edited 2013-05-21 18:15:22 by BenedictReuschling)