Welcome to the FreeBSD June 6 Doc Sprint

Agenda:

• feasability of a doc wiki with contributor write access 
• dead tree Table of Contents: do we divide entire Handbook into 3 or does it  make more sense to publish sections that belong together? 
• status of perforce for dead tree version 
• publication goals for 2011 
• further discussion on selling Kindle/epubs with proceeds going to Foundation 
• status of getting someone to write FreeBSD weekly summaries / assist @hrs with Release Notes 
• short status report about the cvs->svn conversion (@bcr) 
• set date(s) for docathon(s) to work on and hopefully close doc PRs 
  
  
  
  
  
  

DISCUSSION:

- postgres releases versions of documentation, so don't have to make doc match every possible version: see http://www.postgresql.org/docs/manuals/
--- This may either be possible through a head/branches/MFC-type approach, mirroring src, or possibly with SGML tags. Branching is much easier with SVN, so we probably do that after we made the switch from CVS.
- postgres also provides commented and uncommented versions

- examples of sites using ReST (http://docutils.sourceforge.net/rst.html): http://docs.openstack.org/, http://www.varnish-cache.org/docs/trunk/, http://docs.python.org/py3k/reference/expressions.html
-ReST supports PDF, HTML, epub generation
-ReST can be hooked into mediawiki 
-py-docutils on FreeBSD and rst2html on MacOSX are possible converters; sphinx is for larger doc conversion (http://sphinx.pocoo.org/)
-may need to use ReST's built in macros or pre-processor to understand all of our formatting needs
-ReST directives: http://docutils.sourceforge.net/docs/ref/rst/directives.html

- http://piwik.org/ is an open source alternative to Google Analytics and there is a port
- logs have not been mined in years as analog installation broke

- FreeBSD weekly summaries would be nice, but is hard to do. Zeising (aka Erandir) and bcr@ will try to compile something resembling http://replay.web.archive.org/20060527162839/http://excel.xl0.org/FreeBSD/13-12-04.html which could also be used for easier release notes generation.

TODO:

- create a port for etherpad so can run on our own server for meetings

- schedule next doc sprint

- move http://wiki.freebsd.org/SubversionPrimer/Merging from wiki to committer's guide

- Try to convert some small subset of the documentation (such as commiters guide) to reStructuredText (Zeising, aka Erandir)

- research if kindle will support epub format and if Amazon sells epub format; Foundations also asks what is the process to get on Google Books (Sam Leffler can assist if needed)

- email Josh to see how postgres manages their docs (e.g. comments)

svn2cvs:
gavin@ has made a start at converting CVS to SVN, and is building up cvs2scvn config and option files.  The resulting repo mirrors the structure of the src repo, with head/, release/ etc.
For cvs to svn conversion, simon volunteers to help out with merging into svn.FreeBSD.org etc. Open infrastructure parts which need to be done:
- www.FreeBSD.org build scripts convert to svn (includes blue, sky etc)
- FTP doc build scripts
- ACL handling
- Mailing lists handling
- Scripts and tools used to keep track of translations

TAKEAWAYS:

- schedule weekly irc doc meeting at varied days/times to allow for timezone participation, meeting to be archived for those who can't make it
- The general consensus is that we should not move to a wiki-only documentation (like some projects have). Instead, we should keep the doc repository (long term project history) and the wiki (easier editing) for parallel work.
- Some interest in ReST was shown. More testing is needed to get a feel for what we gain and lose with it.
-epub/kindle version is certainly feasible, without much work.
-Dead Tree version requires a lot of work, on the other hand, and perhaps a division into more than one book. Another drawback is also that money from sales goes to BSD Mall instead of FreeBSD foundation
- For going to svn there does not seem to be a need to maintain CVS after switchover, IE no svn2cvs.

PRS CLOSED:

http://people.freebsd.org/~linimon/annotated_prs.docsprint.html



PRS THAT COULD BE CLOSED:
http://www.freebsd.org/cgi/query-pr-summary.cgi?category=doc&state=patched