FreeBSD Devsummit 09-2014 Documentation WG Summary by Benedict Reuschling

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