FreeBSD's Google Season of Docs Idea List

Introduction

FreeBSD is an operating system used to power modern servers, desktops, and embedded platforms. A large community has continually developed it for more than thirty years. Its advanced networking, security, and storage features have made FreeBSD the platform of choice for many of the busiest web sites and most pervasive embedded networking and storage devices.

FreeBSD is currently keeping it's documentation (books, articles, FAQ, website) in the following Subversion repository: https://svnweb.freebsd.org/doc/

The FreeBSD Documentation Project Primer is your guide to contributing to FreeBSD's docs. It contains a Quick Start section that tells you everything you need to know to get started. For further information, please contact the mentors for the task or ask on IRC FreeNode channel #bsddocs for help.

Documentation Project Idea List

Project

Description

Mentors

Related material/Links

Website Conversion to Hugo

The main FreeBSD.org website is currently built using a combination of DocBook XML that are generated using Makefiles. Since the content is mostly static, this project will replace it with Hugo, a static site generator framework. This allows easier maintenance of webpages, changing of themes, and posting news and content updates on the front page. The project should convert the main website and sub-pages like News, upcoming events, Downloads, Links, etc. (basically everything what is there now).

GuangyuanYang, BenedictReuschling, SergioCarlavilla

FreeBSD.org website, Hugo

Update the ZFS handbook chapter

OpenZFS is a modern filesystem with integrated volume manager that is available on FreeBSD and described in the handbook. The objective of this task is to update the handbook chapter with the current features that OpenZFS has to reflect the current state in FreeBSD. The delegated administration section needs to be expanded with examples to cover the delegation of ZFS administration to users and groups. A new section on ZFS replication (send/receive) should be written that is referencing the delegated administration section to allow unprivileged users to run ZFS replication (for backups). Boot environments (BE) should be described and how they can be used using the bectl. This should include creation of a BE, listing them, and switching to one, including a screenshot from the boot loader where they can be selected. The Tuning section should be updated and expanded with recommendations how which sysctls can be used to tune ZFS on FreeBSD.

BenedictReuschling

ZFS handbook chapter

Update jails handbook chapter

The jail chapter should be updated to reflect the current state of Jails in FreeBSD. Ressource limits and VIMAGE should be described and how to set up jails using these mechanisms. Tips and recommendations on memory and disk space use should also be added.

Jails handbook chapter

Update X11 and Graphics handbook chapter

The X11 handbook chapter should be updated to reflect the current use of FreeBSD graphics. It should describe which drivers to load for different graphics cards (legacy or modern) and how to set up a basic desktop environment using he accelerated graphics power available from these drivers. Also, changing screen resolution in the console for BIOS and UEFI should be described (screenshots welcome) to show the various capabilities of the vt console driver.

vt man page, Graphics

Create a Wine handbook chapter

WINE is a compatibility layer that allows running certain Windows binaries under POSIX-compliant operating systems. The support for WINE under FreeBSD should be described, how to install it, set it up, and run an example binary (including screenshots).

BenedictReuschling, AlexanderLeidinger

WINE website, Wine

Write a chapter on Testing in the developers handbook

FreeBSD includes a comprehensive testing framework called kyua. Writing tests using that framework should be described in the developers handbook so that developers can write more tests. It should contain where tests are located, how to run them, and how to write a simple test case (walkthrough).

FreeBSD developers handbook kyua

Document configuring bsnmpd

The bsnmpd daemon is handling SNMP on FreeBSD. Its configuration may be complex and should be explained in the FreeBSD handbook for users. The minimal common settings should be introduced in a section of the Network Servers chapter. Pros and cons (security concerns) should also be mentioned and how to use SNMP (including MIBs, receiving data from a remote system, traps, etc).

Merge and extend the LDAP article into the handbook

FreeBSD supports LDAP authentication and describes it in its own article. The article needs updating to reflect current LDAP server versions and clients. It should subsequently be merged into it's own handbook chapter under Network Servers chapter to show how to set up an LDAP server or connect to one using a client. A different LDAP client that is more modern should be described (setup and configuration), for example nss-pam-ldapd.

LDAP Authentication article

Write missing man pages

There is a list of missing man pages. Start writing as many man pages from that list as possible. With the help of your mentor, find the author or someone who recently changed the source file that the man page in question is about for background information and details.

GuangyuanYang, BenedictReuschling

Missing man pages

Add EXAMPLE sections to man pages

The FreeBSD man pages include in many places an EXAMPLE sections, describing basic usage of the utility or command described therein. The FreeBSD wiki has a list of man pages without examples. Add as many examples to these man pages as possible in cases where it makes sense to have them. Come up with a general way of introducing the command/utility in these sections (i.e. quick start first, more advanced examples afterwards) and apply that to man pages describing similar utilities/commands. That way, the examples have a consistent approach and the reader can find things easier.

BenedictReuschling

man pages without examples

Integration in Windows AD

Write a guide how to integrate FreeBSD into an existing Windows AD domain (involves kerberos / LDAP / maybe even changes on Windows side).

Maybe Linux based guides provide a starting point.

Windows shadow copy via samba+ZFS

Samba has a shadow copy plugin, which allows Windows users to recover old versions of files. Write a guide how to handle that with ZFS (ways of doing automatic snapshots for ZFS (ports), smb config, ).

BenedictReuschling, Co-Mentor: AlexanderLeidinger

Samba docs, ZFS on Linux guide, several snapshot management ports

Integration of FreeBSD into an existing SAN

This is about fibre channel stuff (iSCSI is already explained in the handbook)... Document which HBAs we support, and how to use / attach a LUN.

More End-User-style HOWTOs

add more ports related HOWTOs with a focus on end-to-end (integration of all tiers in a multi-tier setup), e.g. setup of a complete mail solution (MTA (postfix, exim, sendmail, ...), IMAP (dovecot, ...), anti-spam/av (rspamd, mailscanner, clamav, ...), DB (postgres, mysql, ...), webmail (horde, roundcube, ...), statistics), or a FreeBSD based monitoring solution (nagios, zabbix, icinga, cacti, prometheus, netdata...), or ...

BenedictReuschling Co-Mentor: AlexanderLeidinger

pNFS and NFS over TLS Howto

Add a howto article or handbook section that explains how to setup and use parallel NFS (pNFS) and NFS over TLS. Illustrations and/or diagrams would be helpful to add, too.

BenedictReuschling Co-Mentor: RickMacklem

NFS handbook chapter


CategoryDocs

GoogleSeasonOfDocs (last edited 2020-06-04 08:55:00 by BenedictReuschling)