Posted on 2014-05-20 08:00:00
Tags: Riverbed, Books
My first book, named Troubleshooting Riverbed Steelhead WAN Optimizers, has been published officially. Well, made available to Riverbed customers with access to the Riverbed Support website. It has been a multi-year effort and as usual the most difficult part was to get approval for external publishing.
The things that went smooth were the editing and the publishing: That approach was taken more or less from how the FreeBSD Project makes their documentation: The source is based on DocBook XML (Was DocBook SGML when I started) which compiles it into various formats like HTML, PDF and ePub. This makes sure you have the style and the content separated, so that even if you make certain style changes afterwards you just do it in the style sheets and it automatically propagates through the whole output without the fear of missing a part somewhere in the text.
But after two chapters of that SGML/XML, I had enough of the excess of markup tags like <para> and <sectx> which presence made my automatic reformatting habbit spending more time on the smoothness of the tags than on the content. Time for a different approach!
In the past I have worked with HTML, various *roff formatters and Perl's perldoc and ended up with a mixture of things: Use the *roff .-prefix to initiate a command, use the HTML h1-h5 and i/tt/b kind of tags for the commands and use the automatic approach of perldoc to know where the paragraphs end. And then you end up with something like:
.h2 Steelhead xx20 series models The xx20 series models consist of a set of desktop models, 1RU rack models and 3RU rack models. To upgrade between models, except [...] .h3 No route to host A .i No route to host error is shown when the remote host does not exist and the router on that subnet sends back an ICMP Host Unreachable message or when
After that a convertor changes it into a real DocBook XML document:
which then gets converted into HTML or PDF.<sect2 ><title>Steelhead xx20 series models</title> <para>The xx20 series models consist of a set of desktop models, 1RU rack models and 3RU rack models. To upgrade between models, except [...] <sect2 ><title>Telnet failure scenarios</title> <sect3 ><title>No route to host</title> <para>A <emphasis role="italics">No route to host</emphasis> error is shown when the remote host does not exist and the router on that subnet sends back an ICMP Host Unreachable message or when
Easy editing, easy markup, easy publishing. That worked fine. The book was used internally at Riverbed for training the new TAC engineers and everybody was very excited about it.
What didn't go smooth was to get the approval to publish it to customers. Everybody saw the value in the book, realized that education at this part could help releasing pressure on the TAC engineers and improve the customers Steelhead experience.
But nobody knew how to take up the book and help to get approval to make it available for the outside world. People who promised to help me moved outside Support or outside Riverbed, I was pushed around by various departments to the same various departments which already told me earlier that I should talk to the people who just send them back to me. It shouldn't be so difficult, the TAC does have access to the full contents of their own website and the TAC does publish KB articles of various quality levels without going through proper review before they get published.
So after three years of editing and publishing internally and trying to get it to the outside world, it has finally been done: My first book named Troubleshooting Riverbed(r) Steelhead(r) WAN Optimizers is available for the Riverbed customers. You can download it at http://rvbd.ly/1p5MMgu or http://supportkb.riverbed.com/support/index?page=content&id=S24051.
| Share on Facebook | Share on Twitter