Introductions: marcel, Simon Gerraty, jonathan, brd, zeising, gavin, pgj, issyl0, dru, gjb

1. Printed edition of the Handbook. There is still a desire for an updated printed version of the handbook. What do we need to do to make this happen? 2. Rearranging the handbook, possibly moving content elsewhere that shouldn't be in.

Discussion re: printed handbook. Initial suggestion of three books (install, server, desktop), but discussions tended towards only needing a single book with install and desktop chapters or sections.

Desire to rearrange web handbook to more match how we'd imagine printed book to be. Some sections (e.g. printing) possibly far too detailed.

What is the target audience?

publican tool mentioned on DocSprints

once we are on XML, publican can be used to pick and choose what goes into an epub/pdf--publican is now a FreeBSD port (textproc/publican)

Discussion about how handbook laid out (using Kerberos as the example) - currently basic use of Kerberos as a client is in the same chapter as setting up your own Kerberos realm - why? The two sets of users are very different. Probably split "client" vs "server" content, perhaps linking to common "Kerberos theory" type section.

Is DocBook still the best choice for doc source? Discussions around reStructuredText etc. (rwatson) Writing documentation in the first place is generally much easier than keeping it updated, partially due to the markup. Doxygen? Allowing comments on the website doc pages would be good

Book really needs an editor (paid by Foundation/Mall?) for a month-ish prior to publication

3. Migration Guide for Downstream Consumers (Switching from CVS to SVN)

4. Getting more src committers to contribute and update documentation

Why do man pages get updated more than doc/ pages?

Can we get going?

LLVM has an upcoming "Doxygen checker" that will verify the documentation matches the code at compile time :)

5. Website (Thoughts on updates/layout/redesign?)

Download site should be redesigned, it is too complex.

Need a nice 404 page!

Who is the (target) audience (of the front page)?

(home page) Wish list:

On the front page:

6. Translation

  1. Out of date translations on the website
    1. Should they be unlinked? svn rm'd?
    2. How do we get new language contributors bootstrapped?
  2. Notification for when translations need updating
    1. pgj's script works well for several projects
    2. Can we extend it to all projects? Is this useful?
    3. Can we export the results to a web page to give an overview of translation state?
  3. Translations to new languages, what do we do with them?
  4. Base system translation. At the very least, having the installer in native language might be nice.
    • Need unicode on system console first.

7. Official PkgNg documentation for individual use and site-wide development

  1. In progress (I think) by wblock@ and swills@ b. Some questions gjb@ has specific to users maintaining their own pkgng repository:
    1. What to consider to be the "official" packaging tool?
      1. ports-mgmt/poudriere :
        • - requires a machine using the ZFS filesystem.
        b. ports/mgmt/tinderbox :
        • - requires an extensive amount of configuration and/or maintenance on
          • the end-user side
          - jail(8) support (somewhat still) broken in CVS HEAD - No pkgng support in ports-mgmt/tinderbox (requires ports-mgmt/tinderbox-devel)

8. Outstanding Google Code-In stuff?

GoogleCodeIn/2011Status are the outstanding patches created as part of Google Code-In 2011.

Action items


DevSummit/201208/Documentation/Notes (last edited 2021-04-25T07:13:36+0000 by JethroNederhof)