Show pageOld revisionsBacklinksBack to top This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong. ====== 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 Git repository: https://cgit.freebsd.org/doc/ The [[https://docs.freebsd.org/en/books/fdp-primer/|FreeBSD Documentation Project Primer]] is your guide to contributing to %%FreeBSD%%'s docs. It contains a [[https://docs.freebsd.org/en/books/fdp-primer/#overview-quick-start|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 ^ | Document formatter | The %%FreeBSD%% has some rules about how documentation source files should be formatted (indented). Doing this manually is a tedious task and turns people away from writing documentation due to the formatting overhead compared to writing the actual content. An automatic formatter should be able to run over source files and reformat them according to our rules. The rules are outlined in the %%FreeBSD%% Documentation Project Primer and in textproc/igor. | | | | 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 [[https://www.freebsd.org/cgi/man.cgi?query=bectl&apropos=0&sektion=0&manpath=FreeBSD+12.0-RELEASE+and+Ports&arch=default&format=html|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 | [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/zfs.html|ZFS handbook chapter]] | | Update jails handbook chapter | The [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/jails.html|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. | | [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/jails.html|Jails handbook chapter]] | | Update X11 and Graphics handbook chapter | The [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/x11.html|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 [[https://www.freebsd.org/cgi/man.cgi?query=vt&apropos=0&sektion=0&manpath=FreeBSD+12.0-RELEASE+and+Ports&arch=default&format=html|vt]] console driver. | | [[https://www.freebsd.org/cgi/man.cgi?query=vt&apropos=0&sektion=0&manpath=FreeBSD+12.0-RELEASE+and+Ports&arch=default&format=html|vt man page]], [[Graphics]] | | Write a chapter on Testing in the developers handbook | %%FreeBSD%% includes a comprehensive testing framework called [[TestSuite|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). | | [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/|FreeBSD developers handbook]] [[TestSuite|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 [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-servers.html|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 [[https://www.freebsd.org/doc/en_US.ISO8859-1/articles/ldap-auth/index.html|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 [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-servers.html|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 [[https://www.freshports.org/net/nss-pam-ldapd/|nss-pam-ldapd]]. | | [[https://www.freebsd.org/doc/en_US.ISO8859-1/articles/ldap-auth/index.html|LDAP Authentication article]] | | Write missing man pages | There is a list of [[MissingManpages|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 | [[MissingManpages|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 [[ManPagesWithoutExamples|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 | [[ManPagesWithoutExamples|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 | [[https://www.samba.org/samba/samba/docs/man/manpages/vfs_shadow_copy2.8.html|Samba docs]], [[https://github.com/zfsonlinux/zfs-auto-snapshot/wiki/Samba|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 [[http://people.freebsd.org/~rmacklem/pnfs-planb-setup.txt|setup and use parallel NFS (pNFS)]] and [[http://people.freebsd.org/~rmacklem/nfs-over-tls-setup.txt|NFS over TLS]]. Illustrations and/or diagrams would be helpful to add, too. | BenedictReuschling Co-Mentor: RickMacklem | [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/network-nfs.html|NFS handbook chapter]] | ---- {{tag>Docs}} googleseasonofdocs.txt Last modified: 2021/03/21 11:25by SergioCarlavilla