
Sign up to save your podcasts
Or
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
“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.“
“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).“
We brought you the news about sponsoring the Advanced ZFS book that MWL is working on, now Michael has given us the tentative chapter layout of the (sure to be a classic) tome coming from him and Allan.
In addition to the tease about the upcoming book, michael has asked the community for assistance in coming up with the cover art for it as well.
In particular it should probably be in-line with his previous works, with a parody of some other classic art-work.
If you have something, go tweet out to him at @mwlauthor
Online registration for AsiaBSDCon 2016 now open SOON
BhyveCon 2016
NYC*BUG shell-fu talk slides
Possible regression in DragonFly i915 graphics on older Core2Duos
Videos from FOSDEM 2016. BSD dev room was k4601
4.9
8989 ratings
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
“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.“
“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).“
We brought you the news about sponsoring the Advanced ZFS book that MWL is working on, now Michael has given us the tentative chapter layout of the (sure to be a classic) tome coming from him and Allan.
In addition to the tease about the upcoming book, michael has asked the community for assistance in coming up with the cover art for it as well.
In particular it should probably be in-line with his previous works, with a parody of some other classic art-work.
If you have something, go tweet out to him at @mwlauthor
Online registration for AsiaBSDCon 2016 now open SOON
BhyveCon 2016
NYC*BUG shell-fu talk slides
Possible regression in DragonFly i915 graphics on older Core2Duos
Videos from FOSDEM 2016. BSD dev room was k4601
1,971 Listeners
272 Listeners
283 Listeners
265 Listeners
215 Listeners
154 Listeners
65 Listeners
189 Listeners
181 Listeners
44 Listeners
21 Listeners
135 Listeners
92 Listeners
29 Listeners
47 Listeners