D
dlavigne
Guest
This is a long post. If you are TLDR;, please at least skim through this before complaining about the current doc transition :)
The FreeNAS project has published a User Guide for each major software version since version 8.0.1. The platform for making the documentation has been mediawiki, which allows for collaborative editing of the upcoming version. This makes it easy for anyone to contribute to the documentation as they only need to make a wiki account and mediawiki formatting is fairly quick to learn and well documented. However, this method has several disadvantages:
- the mediawiki was meant to provide an easy way for many users to edit the upcoming version of the Guide; however, since it is findable by search engines, Internet search users were finding documentation that did not necessarily match their version of FreeNAS. FreeNAS is a rapidly moving target wrt to features and the look of the GUI config screens, which is why reading the docs for the installed version is important.
- mediawiki really sucks at creating different outputs; trust me, we've tried and failed at every mediawiki plugin. It just wasn't designed to make decent looking PDFs or versioned HTML. It also doesn't really understand the concept of a Table of Contents and how to use one to generate one cohesive document. The workaround for this was to copy/paste the mediawiki content into an OpenOffice document and use that document to export to other formats. This sucked on many levels. It meant that one person (me) had to track every wiki change and make sure it made it into the OpenOffice document. While OpenOffice does a good job of generating PDFs, there are no polite words to describe what it does when creating HTML. The generated HTML was so bad, we stopped making them after the 8.3.1 release. Not having an easy way to generate HTML brings us back to that Internet search problem. While we can stress that users need to grab the PDF for their version, that's not going to mean anything when any Internet search will happily bring them to the mediawiki page for the upcoming version.
Since April, I have been converting what will be the 9.3 docs from mediawiki to reST format. This is the format used by the FreeNAS API documentation and by many other open source projects. This format offers several advantages:
- it integrates into github, meaning that the docs are included with the FreeNAS source code
- it integrates into the build system, meaning that edits to the docs can be immediately pushed to the doc website
- it automatically generates decent looking HTML and can instantly build decent looking PDFs, EPUBs, and other formats
- the formatting syntax is easy to learn
- moving forward, it solves the Internet search problem. While 9.3 is the current upcoming version, it will be the current version in the next month or so. Once 9.3 is released, we simply have to start another HTML page for the next version of FreeNAS.
It is important to note that we are currently in a transition phase. If you go to doc.freenas.org, it still provides the list of archived docs and indicates their release dates. Remember, unless you are testing nightlies, you still want to use the PDF (and possibly ERRATA) for your release. Since it took nearly 2 months of solid work to migrate the 9.3 docs into properly formatted reST, we simply don't have the man hours to convert all of the existing docs to the new format. This means that they will continue to be available in their current PDF format. For upcoming FreeNAS versions, the "nightly" HTML will be available for the upcoming version and the "published" HTML will be available with each release, starting with 9.3. Moving forward, we will also publish PDFs for each version and will see if other formats are also useful to publish.
For users who are interested in assisting with doc edits, instructions for getting started are at https://github.com/freenas/freenas-docs/blob/master/README.md. Feel free to ping me if you need help getting started. If you have a simple change you would like to see committed you can also ping me through the forums, IRC channel, or doc mailing list and I can commit the edit for you.
The FreeNAS project has published a User Guide for each major software version since version 8.0.1. The platform for making the documentation has been mediawiki, which allows for collaborative editing of the upcoming version. This makes it easy for anyone to contribute to the documentation as they only need to make a wiki account and mediawiki formatting is fairly quick to learn and well documented. However, this method has several disadvantages:
- the mediawiki was meant to provide an easy way for many users to edit the upcoming version of the Guide; however, since it is findable by search engines, Internet search users were finding documentation that did not necessarily match their version of FreeNAS. FreeNAS is a rapidly moving target wrt to features and the look of the GUI config screens, which is why reading the docs for the installed version is important.
- mediawiki really sucks at creating different outputs; trust me, we've tried and failed at every mediawiki plugin. It just wasn't designed to make decent looking PDFs or versioned HTML. It also doesn't really understand the concept of a Table of Contents and how to use one to generate one cohesive document. The workaround for this was to copy/paste the mediawiki content into an OpenOffice document and use that document to export to other formats. This sucked on many levels. It meant that one person (me) had to track every wiki change and make sure it made it into the OpenOffice document. While OpenOffice does a good job of generating PDFs, there are no polite words to describe what it does when creating HTML. The generated HTML was so bad, we stopped making them after the 8.3.1 release. Not having an easy way to generate HTML brings us back to that Internet search problem. While we can stress that users need to grab the PDF for their version, that's not going to mean anything when any Internet search will happily bring them to the mediawiki page for the upcoming version.
Since April, I have been converting what will be the 9.3 docs from mediawiki to reST format. This is the format used by the FreeNAS API documentation and by many other open source projects. This format offers several advantages:
- it integrates into github, meaning that the docs are included with the FreeNAS source code
- it integrates into the build system, meaning that edits to the docs can be immediately pushed to the doc website
- it automatically generates decent looking HTML and can instantly build decent looking PDFs, EPUBs, and other formats
- the formatting syntax is easy to learn
- moving forward, it solves the Internet search problem. While 9.3 is the current upcoming version, it will be the current version in the next month or so. Once 9.3 is released, we simply have to start another HTML page for the next version of FreeNAS.
It is important to note that we are currently in a transition phase. If you go to doc.freenas.org, it still provides the list of archived docs and indicates their release dates. Remember, unless you are testing nightlies, you still want to use the PDF (and possibly ERRATA) for your release. Since it took nearly 2 months of solid work to migrate the 9.3 docs into properly formatted reST, we simply don't have the man hours to convert all of the existing docs to the new format. This means that they will continue to be available in their current PDF format. For upcoming FreeNAS versions, the "nightly" HTML will be available for the upcoming version and the "published" HTML will be available with each release, starting with 9.3. Moving forward, we will also publish PDFs for each version and will see if other formats are also useful to publish.
For users who are interested in assisting with doc edits, instructions for getting started are at https://github.com/freenas/freenas-docs/blob/master/README.md. Feel free to ping me if you need help getting started. If you have a simple change you would like to see committed you can also ping me through the forums, IRC channel, or doc mailing list and I can commit the edit for you.
Last edited by a moderator: