Here are some TODO items for The FreeBSD Documentation Project. Some of these are smaller tasks, which are relatively easy to solve and some are more complicated, longer term tasks.

Note: Just because an idea is on this page it does not mean there is guarantee that there exists a consensus that the idea is a good one.

Long term targets: DocLongtermTargets

Documentation Project TODO List

Task

Description

Status

Responsible

Convert docproj/todo.html to the DocIdeaList

The TODO list needs to be merged over to the Wiki, and docproj/todo.html needs to be retired.

Not started

GlenBarber

VCS

Task

Description

Status

Responsible

Define a good SVN layout

To migrate the doc+www sources to Subversion, first we need to define a good layout for the new repository.

Completed

doceng, see their announcement for more info

Convert the CVS repository to SVN

Do the actual migration.

Completed

doceng, see their announcement for more info

Set up CVS exporter

We still need to provide the sources in CVS for CVSup servers and to feed out Perforce development repository.

Cancelled. Evaluated to be unnecessary.

doceng

Documentation Infrastructure

Task

Description

Status

Responsible

Entity cleanups

Entities may be organized much better than we do currently. Sometimes, entities logically belonging to the same category are split into various files (trademarks.sgml and trademarks.ent) and translations do not use entity sets correctly. It seems that the general concept is not widely understood and some translations just copy English entities instead of pulling them in appropriately. This should be cleanup up and simplified in order to avoid later misuses.

Completed

GáborKövesdán

Migrate to DocBook 4.2/XML

SGML is quite an old standard and (Open)Jade is an outdated software, whose development is discontinued. XMLifying our documentation set would give us the opportunity to use a more modern toolset and newer standards. It has a lot of advantages, which do not fit here. This task implies upgrading the DTD to 4.2 because that is the first version, where XML is also supported.

Completed

GáborKövesdán

Use XSL to generate HTML output

After XMLifying the doc tree, we should replace (Open)Jade for HTML output generation. This is quite trivial, while the RTF, PS and PDF outputs are more problematic.

In progress

GáborKövesdán

Evaluate xmlroff and Apache FOP for RTF, PS and PDF rendering

It would be nice if we could totally replace (Open)Jade after XMLifying the tree and xmlroff may be a good candidate for this. However, when GáborKövesdán last checked it, its output was not mature enough. Apache FOP generates a very high quality output but it is written in Java, which may be an expensive dependency. At least optional support for these tools should be added even if they cannot replace (Open)Jade yet.

In progress

GáborKövesdán

XHTMLify webpages

Just like for our DocBook documentation, the SGML vs. XML question also applies to the webpages, so they should be migrated to XML to use a more modern toolset.

Completed

GáborKövesdán

Move webpages to the doc directory inside the top-level language directories

To facilitate information sharing between documentation and webpages, it would be practical to move the webpages next to the articles and books directories.

Completed

HirokiSato

Make web script multilingual

Our main Web pages are written in (American) English. The FreeBSD Translations Projects translate the web pages, Handbook and FAQ to other languages. We must translate the cgi scripts and web build scripts too. The scripts should support multiple languages, not only one. Most scripts are written in perl. Merge the perl scripts www/en/ports/portindex and www/ja/ports/portindex into one script. Add an option for English and Japanese output.

Not started

Not assigned

Enhance search engine

When searching the website, the output from the search engine includes the filename that was found, which might be something like FAQ34.html. It would be more useful if the results included the question text, allowing the user to see whether or not the result was relevant.

Not started

EricAnderson

Website

Task

Description

Status

Responsible

Dynamic web app for project ideas

Murray has started a project to move the static ideas.xml file used to keep track of summer of code and other development projects seeking volunteers into a dynamic web app that allows users to vote and post comments about the items so that it is clear which projects have the most support and so that it is easier to make updates. See the design doc in IdeasWebApp

Unknown

MurrayStokely

XMLified publications page

JosefElRayes started with XML'ifying the Publications Pages. I will try to make it up to date like the UserGroups and perhaps implement information found on this XSLT/XML info into the UserGroups. Reference: PR www/59307

In progress

RemkoLodder

XML/XSL-based web calendar

With some nice xml/xsl code (based on simons eventscalendar) we could create a nice calendar that covers all needed dates, like releng dates, freezes and so on. it could be reused multiple times on the website. Some XSL or Perl code could also make it create some calendar(1) or perhaps even ical compatible output.

Unknown

JosefElRayes

Review http://www.freebsd.org/java/

Review http://www.freebsd.org/java/ and suggest improvements. A lot of information over there is probably highly outdated and there may be quite a few dead links.

Not started

Not assigned

Track down and solve rendering issues

After the introduction of new layout, many persons reported a font size or rendering problems under some browsers configurations and screen resolutions. These problems should be investigated and fixed. Reference: http://www.freebsd.org/cgi/query-pr.cgi?pr=91539

Not started

Not assigned

Refactor CGI scripts

Modify the CGI scripts url.cgi, ports.cgi, pds.cgi and the script portindex to use the Perl FreeBSD::Ports modules. These modules also need thorough testing.

Not started

WolframSchneider

Handbook

Task

Description

Status

Responsible

Add a section to the network servers chapter on setting up JBoss

Tomcat is merely a Java web container so it cannot run e.g. EJB3. In such cases, an application server, like JBoss is necessary. We lack information on how to use it on FreeBSD.

Not started

Not assigned

Add some info on how to tune network performance

On NetworkPerformanceTuning, there are some tunables and sysctls listed. Those should be explained in handbook.

Not started

Not assigned

Extend jails chapter with tips and useful utilities

The Jails wiki page has some tips and useful utilities but the content is rather a sketch. It needs to be transformed an easy to understand fluent text.

Not started

SeanCollins

Add performance tweaks to correspoding chapter

There are some performance tweaks on PerformanceTweaks. These should be merges to the corresponding chapter of handbook.

Not started

Not assigned

Harvest PRs about the handbook

The bugmeisters keep a page of suggested patches to the handbook; it is updated once a day.

Not started

Not assigned

Write a wine section

Some notes are available on Wine.

Not started

Not assigned

Merge available information on ZFS to handbook

We have some pieces of valuable information and references on the ZFS wiki page. These include the quick start instructions, tuning, how to use ZFS for root filesystem, how to install a ZFS-only system, etc. These are quite important notes and should be merged to handbook so that they can get more exposure.

Not started

DavidRhodus

Review information on USB

Check the completeness on how to use USB devices and check if the FAQ entries on the USB wiki page are answered in handbook.

Not started

Not assigned

Review information on ATA/SATA disks

Check if we can merge something from the troubleshooting part of the ATA_issues_and_troubleshooting wiki page.

Not started

Not assigned

Write a javavmwrapper guide

The javavmwrapper tool is powerful, but probably not well-known. Describe the tool in a simple manner and make it available in an official easy to find places. This so that people know how to use the various JDKs that are installed without using aliases or modifying PATH. Same for describing where to find and how to use installed JAR files (see PR/56928).

Not started

Not assigned

Document JDK ports

Provide up-to-date information on the status of the Java SE 5 port, the expectations regarding the Java SE 6 port. Detail the characteristics of the ports, such as stability, security and performance compared to other platforms.

Not started

Not assigned

Update installation chapter

The installation chapter mostly covers FreeBSD 4.X installation. The current information is often outdated and not accurate for 5.X, 6.X and 7.X. We also have to think about installation on various platforms. This should be done under re@ team responsability since the installation notes have to be updated as well.

Not started

GiorgosKeramidas

Add quick and easy setup example to printing chapter

While this chapter covers in a very accurate way the configuration of a printer under FreeBSD, a quick and easy printer setup should be documented, i.e., something describing the installation and use of apsfilter or equivalent.

Not started

Not assigned

Add info on USB printers

Nowadays printers use the USB interface, the printing chapter may need to be updated on this point.

Not started

Not assigned

Merge wireless article to handbook

The merge of this article in the current wireless section should be done quickly.

Not started

MurrayStokely, MarcFonvieille

Update IPsec section

This section still shows the use of gifconfig(4) which is 4.X only.

Not started

RemkoLodder

Review USB audio section

One should check if we need to update the sound section for USB devices or if the current guidances are still correct with these devices.

Not started

Not assigned

Update emergency restore section

This section is really outdated and needs a serious "facelifting." We must show how to restore a system using the livefs from disc1. The rescue system should also be covered.

Not started

Not assigned

Write a section on basic backup

Backing up on optical media (CD/DVD) should be presented.

Not started

Not assigned

Update electronic mail section

The use of Makefile facilities should be introduced for the sendmail configuration instead of the old outdated way.

Not started

JesusRCamou, SeanCollins

Document configuring bsnmpd

The bsnmpd daemon is quite new and its configuration may be complex. The minimal common settings should be introduced in a section of the Network Servers chapter.

Not started

Not assigned

Add some more tips and hints on portupgrade

There are some hints and tips on the portupgrade page, which would fit better into the corresponding part of handbook

Not started

Not assigned

Extract relevant information from Samba mini FAQ and add them to handbook

There are some notes on Samba/MiniFAQ, which would fit better in handbook.

Not started

Not assigned

Improve indexing

Many new sections have been added to the FreeBSD Handbook without index terms, others have been added under inappropriate primary or secondary indexterms that do not fit the existing scheme. Some indexterms have been added inside list items or other areas where they are not allowed by our stylesheets, causing ??? to be printed in the index instead of a real page number. Index work requires experience and anyone who works on this task is highly encouraged to carefully read through the existing (print-output) index, and to have read the Chicago Manual of Style or other style books that deal with indexing. Please see the CVS history of some of the chapter.sgml files to see some of the indexing errors that have been corrected in the past. It is imperative to view the PostScript version of the Handbook after making any changes to indexterms as many errors, such as long words or deeply nested indexterms will break the two column output there, or cause the page number to be listed as ???. There is a script doc/share/misc/indexreport.pl which can be used to find areas of an SGML file where <indexterms> are sparse.

Not started

Not assigned

Update Firewall chapter

The chapter about firewalls in the handbook is becoming seriously outdated. We should also change the order in which the firewalls appear in this chapter. A better order would be: first ipfw, then pf and last ipfilter. The ipfw section should probably be rewritten and it should mention in-kernel NAT.

Not started

Not assigned

Check Configuration and Tuning chapter

The Configuration and Tuning chapter documents some settings which might not be relevant anymore (kern.maxfiles, maxusers, NMBCLUSTERS)

Not started

Not assigned

Update the Serial Communications chapter

Check if the device configuration is now version-independent (modulo node names), add an introduction

Not started

Not assigned

Update the Cutting-Edge Chapter for the Documentation Project CVS->SVN Conversion

ryusuke pointed out in private email that the cutting-edge chapter needs updating since c(v)sup is still mentioned for updating the documentation set. Since we do not do SVN->CVS conversion on the backend, this chapter needs updating. Normally, I would just update/commit, but since the changes will be rather large, I will wait until after the doc slush.

Somewhat Started

GlenBarber

The following list was compiled from the doc session at the EuroBSDCon 2010 Devsummit:

Task

Description

Status

Responsible

Remove SLIP

SLIP is outdated and was removed from the kernel a while ago. Some PRs were sent with patches to remove SLIP from the handbook.

not started

not assigned

Remove ISDN

ISDN has been surpassed by DSL modems and is not being used that often as it was in the past. However, the ISDN mailing list was not removed, so maybe we should discuss whether we still need this section in the handbook.

not started

not assigned

Advanced/Domain specific topics

Some topics that are covered in articles could be moved to the handbook. However, this is not intended to replace the articles in general, just to get their content exposed to a wider audience.

not started

not assigned

More filesystems

There are many filesystems that are available in FreeBSD like TMPFS and others. However, only ZFS is currently being described in the handbook. Add new sections about the other filesystems, their characteristics and usage.

not started

not assigned

Different Installation scenarios

Currently, only the standard installation via sysinstall is described. There are many other good instructions in the FreeBSD Wiki and Forums describing alternative installation methods (i.e. ZFS only, diskless). Add these in a separate section for advanced users.

not started

not assigned

Make security a top level chapter

There are many parts in the handbook that deal with security or have security related content. Security should be a top level chapter for people interested in system security. Appropriate sections need to be discussed (i.e. where to put jails: security or virtualization?) and moved there accordingly.

not started

not assigned

Popular chapters/sections

Analyze which chapters/sections are being accessed the most. That way, we can get a feel for what chapters need more polishing, need to be updated or removed. Something like Google Analytics might be helpful, but other tools might be just as good.

not started

not assigned

EPUB format

The EPUB format is a free and open e-book standard for different electronic devices like ebook readers, tablets or mobile phones. It would be nice to have the FreeBSD handbook in this format so that users can read the handbook on these devices as well.

In progress, see also PublishedFormats or this BSDCan2011 presentation

BenedictReuschling

Print format

There is still a demand for a printed version of the handbook from customers of e.g. FreeBSD Mall. The current third edition covers FreeBSD 4.X and 5.X only. It was recommended to compile the current handbook into three separate books: 1) FreeBSD installation and basic system administration 2) FreeBSD as a server OS 3) FreeBSD as a desktop OS.

Started, see PublishedFormats

not assigned

Mark outdated parts

Some parts of the handbook only apply to older versions of FreeBSD that are still being maintained. In order to let users know that some information applies only to specific versions, we need to mark these sections as outdated with the time of the last update/check.

not started

not assigned

Porters' Handbook

Task

Description

Status

Responsible

Add a section on Haskell ports

This task includes some general notes and the use of the hsporter utility. For the latter, there's a short desctiption here.

Not started

Not assigned

Review and separate user and developer content

Currently, porters-handbook combines some knowledge on using the Ports Collection and knowledge to develop ports. However, it is only meant to be the latter. Content that targets end-users should be moved to handbook.

Not started

Not assigned

Move policies to a more appropriate place

Porters-handbook is for technical details of the development, while it also contains some information on policies. The latter should be moved to the http://www.freebsd.org/portmgr/policies.html part of the webpage to avoid duplication and limit porters-handbook's content more strictly to the topic.

Not started

Not assigned

Better emphasize requirements and recommendations

We (portmgr) have to make it clear what things are Recommendations and what things are Requirements. e.g. exactly what is portmgr willing to enforce with, if necessary, backouts and commit bit suspensions. This way everyone who chafes under any "new policy" can figure out where they stand (whether it is one or the other).

Not started

Not assigned

Reorder introductionary and detailed descriptions

Many things are discussed in detail even before all the general concepts have been introduced. Things need to be reordered.

Not started

Not assigned

Document common practices

About half of the "accepted practices" are missing.

Not started

Not assigned

Review consistency and logical structure of sections

Some of the things in "Do's And Don'ts" appear much too late. Some of the other things aren't even appropriate for that section.

Not started

Not assigned

Reorganize appendices

Some of the text (list of Makevars) needs to come out of where it currently is and be in Appendices. References to the Appendices should then take their place. (Or maybe not.)

Not started

Not assigned

Fill up emacs section

The emacs section is incomplete.

Not started

AndreySlusar

Document new *_DEPENDS style

New *_DEPENDS style with <,>,<=,>= is not described.

Not started

Not assigned

Document porting Mozilla's XPI extensions, NPAPI extensions and Linkfarming

There are some notes on the XPI, NPAPI and Linkfarming pages.

Not started

Not assigned

Document Portscout Variables for Port Makefiles

Port Makefiles support the use of PORTSCOUT variables to limit what Portscout will report as a new version of software. For a quick list, run: find /usr/ports -type f -name Makefile -maxdepth 3 | xargs grep PORTSCOUT

Not started

Not assigned

Developers' Handbook

This book needs more content. It seems a sketch rather than a consistent document. There are lots of uncovered areas but there are some sporadic pieces of information on the wiki, which could be SGMLified and merged to the book.

Task

Description

Status

Responsible

Merge description on Linux cross-development

There is a short description on how to use FreeBSD for cross-developing Linux binaries on linux-xdev. Someone should SGMLify and merge these to developers-handbook.

Not started

Not assigned

Add content on general debugging

Some information may be extracted from Debugging.

Not started

Not assigned

Add content on using profiling to detect performance bottlenecks

Profiling with gprof is very useful to detect performance bottlenecks but it is not widely utilized.

Not started

Not assigned

Add content on dealing with TTYs

Some information of the redesigned TTY subsistem can be found on TTYRedesign.

Not started

Not assigned

Marketing articles

The Marketing Team (marketing@FreeBSD.org) is working on creating a series of whitepapers to explain the advantages of FreeBSD to a general technical audience. This material will initially be linked from the new marketing area of the website, http://www.FreeBSD.org/marketing. Please mail marketing@@FreeBSD.org if you are able to write one of these documents.

Task

Description

Status

Responsible

FreeBSD for Solaris users

Write a short article on FreeBSD for Solaris users. We have support for DTrace and ZFS. Jails can be a good alternative for zones, so it seems we have a good migration path but we need to document it better.

Not started

Not assigned

Clustering with FreeBSD

Write an article on how to plan a clustered system with FreeBSD.

Not started

Not assigned

FreeBSD for hosting providers

Write an article on how to use FreeBSD for common hosting tasks (jails, performance, etc.)

Not started

Not assigned

FreeBSD in embedded devices

Write an article on using FreeBSD on embedded systems

Not started

Not assigned

Building products with NetGraph

Write an article on how to build a FreeBSD-based product with Netgraph.

Not started

Not assigned

Misc

Task

Description

Status

Responsible

Create a source code management book

We use CVS and SVN for mainline development but we also have a Perforce repository and a user area in SVN for experimental development branches. Also, some developers use Mercurial or git for local development. We should collect all information related to the topic to a new book and arrange it in a logical and consistent way. This task would involve SGMLifying the SubversionPrimer (done in this commit), LocalMercurial, and LocalGit wiki pages and merging our Perforce article to the new book. Some kind of introductionary text is also desired to describe how these tools are used.

Not started

Not assigned

Write missing manpages

There is a list of missing manpages on MissingManpages.

Not started

Not assigned

Add some information on power consumption tuning into the laptop article

TuningPowerConsumption has some information on the topic, this may be a good starting point.

In progress, draft

BenedictReuschling

Add an article on why one should choose FreeBSD for Java

Elaborate on why one should prefer running Java on FreeBSD instead of Linux or Solaris. Some information can be found on WhyJavaOnFreeBSD.

Not started

Not assigned

Write section 9 manuals

Document kernel interfaces and functions.

Not started

TomRhodes, HitenPandya

Documenting FreeBSD Tunables

Many FreeBSD tunables are undocumented. Everyone knows how difficult it can be to use an undocumented system, and thus this project was formed. The initial goal here is to create a tool which can generate a manual page with the tunables. Hence we need to generate this list from the source code.

Not started

Not assigned

Write a cups article

The CUPS system is more and more used, it would be interesting to have an extensive article in our documentation set. This article should cover CUPS installation and configuration (with examples of local and network printers).

Not started

Not assigned

Update architecure-handbook

The FreeBSD Architecture Handbook is lacking in content, please help us finish this book in writing or updating some chapters.

Not started

Not assigned

Add description on mirroring GNATS to the hubs article

Review and merge the notes on MirroringGNATS.

Not started

Not assigned

Contribute advocacy slides/presentations

Presentations marked up in the DocBook-slides DTD were added a long time ago to doc/en_US.ISO8859-1/slides. More advocacy content is needed, and additional stylesheet work is needed to pull in content from the release notes and other XML content in our documentation set to build up-to-date slides with 'make'. A simple example presentation was committed with some of this functionality, but there is more work to be done! Also, the stylesheets for print/PDF output (using the Java based XSLT processors, PassiveTeX is too limiting for slides) could be improved as the default DocBook Slides XSL-FO stylesheets produce very spartan slides. To make this really mature, the infrastructure work described above is also very demanded.

Not started

MurrayStokely

Write a section for Handbook and/or FAQ

Chunks of the FAQ and Handbook have empty sections in them. They need filling. If you have just had to use one of these documents to complete a task, and found them lacking, please find the time to write up your experiences as a possible replacement. Alternatively, if you have just had to do something that had no entry in the FAQ and/or Handbook, please consider writing a new section.

Not started

Not assigned

Write new paper on the new SCSI layer for FreeBSD (CAM)

It would be nice to have a detailed description on this subject.

Not started

Not assigned

Release Process

Start collecting some more general notes on the release process, what code freeze means, etc. and update docs.

Not started

BjoernZeeb (not really)

Commit Messages

Probably update the Committers Guide to include more information on the general format and use cases of and for commit message meta-information as Submitted by:

Not started

BjoernZeeb (not really)

R-Pi

Given FreeBSD will soon boot on the r-pi we should ensure to document setup, bringup, use, and possibly later links to cool projects

Not started

Not assigned

DocIdeaList (last edited 2012-10-19 13:17:01 by GáborKövesdán)