As my role has changed at work, so has my main reading material. Gone are a lot of the design and development books (even though I still keep them on a shelf in my office basement) and in are the reams and reams of documentation to try to get up-to-speed both on where we are as a college IT department and where we need to go.
Because of the shift I’m going to take a moment to describe what I would like to see from vendors when it comes to documentation. Let me start with some examples of what I am working with right now.
We currently use Novell NetWare 6.5 for file serving and directory management and authentication. Since we are looking at a migration to Novell Open Enterprise Server 11, I get to spend quite a bit of time with Novell’s documentation. Here is a look at what is available for Novell Filr.
Not bad. A lot of different guides available both as HTML and a downloadable PDF. The documentation itself is quite good, so I don’t have any issue with that. Having it available online is really nice and it is nicely formatted and everything.
I also am looking at SUSE Linux Enterprise Server to help us standardize on a few Linux distributions and because Open Enterprise Server 11 uses SLES 11 as its base operating system. Here is a look at what is available for SLES 11.
Similar to what is being offered by Novell, but there are a few more options! Not just online HTML and a downloadable PDF, but also an EPUB option! So you can load up that file into your eBook reader of choice and enjoy the documentation along with a table of contents and other niceties.
I want to see that from more vendors in the future. What EPUB allows is also the embedding of things like videos and animations into the files as well. That could open up better documentation in the future if time and effort can be dedicated to it.
However, I understand the hesitation as well. EPUB is still not a ubiquitous format with Amazon tying their entire eBook ecosystem to their Kindle formats and Apple using the iBooks format to extend EPUB to something entirely its own. The flip side of that on Apple’s side is that at least iBooks.app can read a standard EPUB.
Maybe ideally, there would be some way to “subscribe” to documentation so that an updated version of an EPUB or some other format might be automatically downloaded and incorporated so that you always have the most up-to-date version. Dash.app does something like that by allowing you to download documentation for various libraries and languages and then have updated versions delivered as they are available.
It is kind of like RSS for documentation.
Moving to something like that would maybe encourage vendors to take the approach of treating documentation as a living document, making changes as flaws are found and also updating it with best practices or even releasing different types or styles of documentation.
That is where I would like to see things move. It feels like the technologies are already out there, but they need to be tested in such a manner and improved upon.
3 replies on “Better Documentation”
Interestingly I just heard something about updating works published through Amazon. Found this help – https://kdp.amazon.com/self-publishing/help?topicId=A1RGGPBKDR1BPZ.
I think the ebook platform is still evolving and at least Amazon is thinking along the lines you are. I hope/expect the platform standard(s) that is the king of the hill in the future has easy free publication methods with rich multi-media content capabilities and easy update.
iBooks does updates as well, I think that it is, at least on the proprietary platforms, a somewhat-solved issue. Combining updates with something like Git (or Mercurial, etc.) so that versions can be merged in without losing track of notes, bookmarks, and highlights is kind of the next thing. Along with that, publication which is separate from a bookstore is another model to try and figure out and how to integrate it into the EPUB (or any other) standard so that updates can be incorporated with any reader which supports standards.
Things are early, yes, but with the “big players” seemingly being content with only playing in their own playgrounds it has stagnated not just the publishing tools but the creation tools as well. I have a feeling that we might be at the IE 6 stage right now and will need to wait for a Firefox to come in and shakes things up to the extent that is needed to push things to the next level.