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)
- Would be nice to have case studies on being a downstream consumer of FreeBSD
- How to effectively contribute back upstream
- git / svn / etc should be documented
- How to handle IP code alongside upstreamable code
- Multiple example workflows with pros/cons? Or a single "This is a good approach"? Is the latter even possible?
- Same document should include reasons why contributing back is good
4. Getting more src committers to contribute and update documentation
Why do man pages get updated more than doc/ pages?
nroff not easier than docbook
- Same repository, does that make a difference?
- Failure modes of "bad nroff" vs "bad docbook" - one breaks build
- Developers use man pages more than doc/ documentation
Can we get doxygen.freebsd.org 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.
- Split dev stuff onto developer.freebsd.org -- a more advanced page tuned towards developers' taste?
Need a nice 404 page!
Who is the (target) audience (of the front page)?
- Current FreeBSD sysadmins
- "User"
- Home / hobbist
- Academia
- ISP / Enterprise IT / CTO
- "Enterprise security"
- Sysadmin
- Product builders
- including the lawyers
NetApp, etc.
- Vendors
- Software
- Service
- Hardware
- Intel-like
- iXsystems-like
- Developers (us!) + hackers
- Downstream consumer, e.g. pfSense, PC-BSD, FreeNAS
- Donors
(home page) Wish list:
- Usable search box
- One-click donation
- Developer dropdown useful
- Feature company page
- Less indirection
- Testimonial loading page
- Mobile version
On the front page:
- What is FreeBSD?
- Download
- Notebook
- Server
- Appliance
- EC2
- Embedded
- Soekris
- Raspberry Pi
- Impression of liveness, responsivity, usefulness
- News
Major consumers / testimonials (short quotes) --> multiple audiences
- Foundation testimonials need to be one page per company, one index page
- Signs of user interactions
- Release dates
- Twitter feed
- Number of downloads
- Release progress
- PC-BSD, FreeNAS, pfSense
- Foundation / Donate
- Forums / mailing lists / contacts / report a bug (Support + Community)
- Documentation
- Search box
- Applications
- Devsummit, developer photos
- Blogs (merge planet.freebsdish.org)
- Debian/kFreeBSD link?
- Link to handbook from "Get FreeBSD" page
6. Translation
- Out of date translations on the website
- Should they be unlinked? svn rm'd?
- How do we get new language contributors bootstrapped?
- Notification for when translations need updating
- pgj's script works well for several projects
- Can we extend it to all projects? Is this useful?
- Can we export the results to a web page to give an overview of translation state?
- Translations to new languages, what do we do with them?
- 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
- In progress (I think) by wblock@ and swills@ b. Some questions gjb@ has specific to users maintaining their own pkgng repository:
- What to consider to be the "official" packaging tool?
- ports-mgmt/poudriere :
- - requires a machine using the ZFS filesystem.
- - requires an extensive amount of configuration and/or maintenance on
- the end-user side
- ports-mgmt/poudriere :
- What to consider to be the "official" packaging tool?
8. Outstanding Google Code-In stuff?
GoogleCodeIn/2011Status are the outstanding patches created as part of Google Code-In 2011.
Action items
- Let's get doxygen.freebsd.org going. (brd@)
- git.freebsd.org needs documentation and a home page (maybe 302 to the docs)
- Being a downstream consumer of FreeBSD (marcel to make notes)