Podcast Episode Details

128: The State of BSD

This week on BSDNow, we interview Nick Wolff about how FreeBSD is used across the State of Ohio and some of the specific technology used. That, plus the latest news is coming your way right now on BSDNow, the place to

This episode was brought to you by

title="DigitalOcean"> src="/images/3.png" alt="Tarsnap - Online Backups for the Truly Paranoid" />

Headlines

Doc like an Egyptian: Managing project documentation with Sphinx

• In case you didn’t make it out to SCALE a few weeks back, we have a great interview with Dru Lavigne over at OpenSource.com which goes over her talk on “Doc like an Egyptian”.
• In particular she discusses the challenges of running a wiki for documentation for PC-BSD and FreeNAS which prompted the shift to using Sphinx instead.

“While the main purpose of a wiki is to invite user contributions and to provide a low barrier to entry, very few people come to write documentation (however, every spambot on the planet will quickly find your wiki, which creates its own set of maintenance issues).

Wikis are designed for separate, one-ish page infobytes, such as how-tos. They really aren't designed to provide navigation in a Table of Contents or to provide a flow of Chapters, though you can hack your pages to provide navigational elements to match the document's flow. This gets more difficult as the document increases in size—our guides tend to be 300+ pages. It becomes a nightmare as you try to provide versioned copies of each of those pages so that the user is finding and reading the right page for their version of software.

While wiki translation extensions are available, how to configure them is not well documented, their use is slow and clunky, and translated pages only increase the number of available pages, getting you back to the problems in the previous bullet. This is a big deal for projects that have a global audience.

While output-generation wiki extensions are available (for example, to convert your wiki pages to HTML or PDF), how to configure them is not well documented, and they provide very little control for the layout of the generated format. This is a big deal for projects that need to make their documentation available in multiple formats.“

• She then discusses some of the hurdles of migration from the Wiki to Sphinx, and follows up with some of the differences using Sphinx you should be aware of for any documentation project.

“While Sphinx is easy to learn, it does have its quirks. For example, it does not support stacked tags. This means, for example, you can not bold italic a phrase using tags—to achieve that requires a CSS workaround. And, while Sphinx does have extensive documentation, a lot of it assumes you already know what you are doing. When you don't, it can be difficult to find an example that does what you are trying to achieve.

Sphinx is well suited for projects with an existing repository—say, on github—a build infrastructure, and contributors who are comfortable with using text editors and committing to the repo (or creating, say, git pull requests).“

Initial FreeBSD RISC-V Architecture Port Committed.

• Touching on a story we mentioned a few weeks back, we have a blog post from from Annie over at the FreeBSD f

  ---

  Published on 9 years, 10 months ago