The document summarizes discussions from the EuroBSDcon 2014 FreeBSD Developer Summit session on documentation. Key points discussed included needing updates to the Handbook chapters on ZFS, networking, storage, and new technologies. Missing or outdated manual pages on iSCSI, bhyve hardware requirements, and tuning were also noted. Suggested improvements to the FreeBSD website included making contributing and communication easier to find, improving search functionality, and ensuring the latest manual pages are available.

1. EuroBSDcon 2014 FreeBSD Developer Summit
EuroBSDcon 2014 FreeBSD Developer Summit
Documentation Session Summary
Benedict Reuschling
bcr@FreeBSD.org
27. September 2014
1 / 12

2. EuroBSDcon 2014 FreeBSD Developer Summit
Overview
Agenda
1 Overview
2 Handbook
3 Manual Pages
4 Website issues/suggestions
2 / 12

3. EuroBSDcon 2014 FreeBSD Developer Summit
Overview
Overview
• Discuss issues developers have with current documentation set
• Q&A session, wants and wishes
• Encouraging developers to review content or provide updates
• Does not have to be formatted, plain text suffices
• Documentation committers can take care of the markup
• File a PR in bugzilla or post to doc mailing list
• Developer input is required to keep up with changes in the system
3 / 12

4. EuroBSDcon 2014 FreeBSD Developer Summit
Handbook
Agenda
1 Overview
2 Handbook
3 Manual Pages
4 Website issues/suggestions
4 / 12

5. EuroBSDcon 2014 FreeBSD Developer Summit
Handbook
Handbook items discussed
Freshly updated ZFS chapter
• Much extended content
• More examples and about pools and zfs options
• Some polishing needed, but better than what we had before
Please read/test and provide feedback!
5 / 12

6. EuroBSDcon 2014 FreeBSD Developer Summit
Handbook
Things that we need to improve
• Examples need testing, some are outdated
• Maybe need some more complicated ones?
• bhyve section needs to document hardware requirements
• Network tuning instructions
• rctl needs more examples for enterprise usage
• NFSv4 chapter update, cover NFSv4.1 specifics
• Missing HPC chapter
• Fibre Channel
• Infiniband
• 10/40GbE
6 / 12

7. EuroBSDcon 2014 FreeBSD Developer Summit
Handbook
Things that we need to improve - continued
• Installing the system without bsdinstall
• scripted installations
• PXE booting
• Jail chapter
• Defining specific jail path
• mention jail.conf
• Installing jails with bsdinstall jail
• Using Config management (puppet, ansible, cfengine, etc.)
• Using FreeBSD in the cloud
• Amazon EC2
• Google Compute Engine
• X11 chapter needs KMS documenting
• VirtIO
• Chapter on monitoring
• vmstat, gstat, more DTrace, other tools in base for system
monitoring)
7 / 12

8. EuroBSDcon 2014 FreeBSD Developer Summit
Manual Pages
Agenda
1 Overview
2 Handbook
3 Manual Pages
4 Website issues/suggestions
8 / 12

9. EuroBSDcon 2014 FreeBSD Developer Summit
Manual Pages
Missing and lacking man pages
• iSCSI - Needs documenting
• bhyve - Man page lacks any info on hardware compatibility etc
• tuning(7) - needs major updates.
• rctl - Needs more detail
• IPv6 - Missing many examples, i.e. how to add a second address
9 / 12

10. EuroBSDcon 2014 FreeBSD Developer Summit
Website issues/suggestions
Agenda
1 Overview
2 Handbook
3 Manual Pages
4 Website issues/suggestions
10 / 12

11. EuroBSDcon 2014 FreeBSD Developer Summit
Website issues/suggestions
FreeBSD.org website issues/suggestions
• Font (too small)
• Info on "how to contribute/give back"needs to be easier to find
• how to communicate with different groups within FreeBSD
• Guide for Newcomers
• Content needs to be easier to find
• Info on how to build only parts of the doc tree (e.g. not all
languages)
• Better results on the search field
• Fix up man.cgi script
• Make the UI more user friendly
• Default to newest version of man pages (not outdated releases)
• Needs to get copies of man pages quicker
• Man pages from all architectures (install them from all arches?)
11 / 12

12. EuroBSDcon 2014 FreeBSD Developer Summit
Questions?
12 / 12