To improve the documentation for pfSense® software and make it easier to use, we are merging the content from the book and the former wiki into a single unified set of documentation available now at https://docs.netgate.com/pfsense/en/latest/.

Once upon a time, there was a documentation wiki for pfSense software. Then along came the official book with even higher quality information. At the time, the wiki was free while the book was available for purchase or via subscription. Eventually we converted the book from DocBook to Sphinx/reStructuredText and later migrated the wiki content from DocWiki to Sphinx to match, though the content remained separate at the time.

In 2018 we released the book content for free to all, leading to a situation where there were two open access sources of truth for documentation from Netgate in the same format. This brought with it several problems, such as duplicate documents, documents about the same topic having large differences in content, or worse, conflicting information. Plus, even though both sets of documentation were accessible on the same site, searching in one did not search both, which was confusing for readers and made it difficult to locate information.

Both sets of documentation contain unique and valuable information, so addressing the situation is not as simple as retiring one set and keeping the other; we have to carefully plan and manually merge the content. This also provides an opportunity to reorganize and clean up document filenames and URLs.

This update focuses primarily on the merge process and reorganization, but we are also updating a few areas of the documentation along the way. We will revise the rest over time, and the work is much easier now that we only have to maintain a single set of documentation.

A few items of note:

  • We setup redirects so that old document URLs will still work. Even when specific old documents no longer exist, redirects will take the user to an appropriate related destination.
  • Nothing of value was lost! We are doing our best to ensure that we only remove duplicate, deprecated, or irrelevant information from the documentation during the merge. Should we receive reports of missing content, we can go back in the repository history and recover items on a case-by-case basis. It is likely that there is more outdated information to clean up, however.
  • We have relocated most how-to/walk-through and example configuration articles into a single “Recipes” section. This terminology has worked well in the TNSR documentation, so following that lead was the logical choice. This allows the main documentation to focus on being a reference for available options and keeps related tutorials and examples together.
  • We relocated most troubleshooting articles into a single “Troubleshooting” section. This makes documentation for solving problems easier to find, and has a similar feel to the old FAQ style used by the wiki content in the past.
  • The documentation no longer uses the repository on Github as it was only for former wiki content. This also means that we can no longer accept pull requests from that repository.

To report issues with the documentation, use the Docs project on Redmine