How to do company documentation?
Apart from my daily tasks in the company, I also occasionally update the part of the internal documentation related to my area. This had started shortly after joining, and after discovering that the existing documents had more archaeological value than anything else. I mean, yes, administration procedures for a 2003 Xserve are interesting, like reading a PDP-11 operations manual. Not useful for daily operations, though.
Worse, they were all Word files, scattered throughout the servers. With that, I couldn’t actually go forward. But, as I’m also writing for ages, I do have experience with different tools to create something useful.
First, there was the question everybody loves: what is the audience. What are their expectations, the level of knowledge? Should I start back when the first human ancestor decided to walk on two legs instead of four? When the multicellular organisms came together?
Maybe not. After some discussion, three groups were identified: first, my immediate colleagues. They’d get the nerdy stuff, nor formatting, no paragraphs, no fancy graphics. The employees would get the other extreme, explanations upon explanations, analogies, proper layout, and pictures. Service and support staff somewhere in between. Three sets, three levels of understanding. And all of it interdependent. Joy.
Structure before Layout
For things like occasionally putting things on Medium, I use Ulysses. It’s fairly easy to master — if you aren’t into creating your own export styles, those can take some time to properly master — while having a no-nonsense UI to keep people like me focused. Furthermore, I happen to like Markdown, while not being a purist about it. The formatting options are simple, but offer enough for most tasks. As an added benefit, you can easily translate it to whatever format you want to have. From an internal web server to a printed copy, and everything in between; including, but, alas, not limited to that Word file.
Naturally, I started there, hoping the project itself would be done in a couple of weeks by creating a bunch of files for each topic. Looking back at myself during that time, and I’m looking at a very naive person.
Naïveté is also self-evident in my next undertaking. Instead of actually doing just one file per topic, I chose to think about it first. Always a bad idea. But, so I wondered, what would I expect from any decent documentation? Followed by — how would I prefer to read it? Apart from those scattered files, there were also forgotten documents within the ticketing system in use. Horrible things, using the worst formatting ever, having been created in Word and converted into a webpage. Utterly fascinating in its ugliness. Back to the topic.
For me, a key point in any form of documentation is linking to different parts, maybe a glossary, further in-depth explanations, related topics — the works. Basically, everything should have an index, a clear and concise structure around the topics, and — yes — a comprehensive glossary. None of that was in existence, so I was free to create my own.
Having that firmly in my mind, I was ready to roll.
My sweet setup
(A word of warning: my workflow is working for me, and it’s certainly not for everyone. In fact, me being somewhat strange, I’d be astonished if it would work for you.)
Naturally, I used Ulysses for the first draft, even if it lacks linking to other sheets — that’s Ulysses-speak for files. Creating the basic structure — folders, sub-folders, files — while omitting any pictures (graphics, pictures) or tabular data; yet marking the place where I’ll put them in later. From the first rush (I couldn’t call it a draft, honestly. Is there a level like pre-drafting?) I did go on and produced what every author I know would call a draft (the rush is rarely readable, just a collection of notes about that specific topic). At that point, it is borderline readable. Still, lacking any form of polish. Like a glossary. Or pretty pictures. And so on.
But placeholders.
Having that out of my hair, I exported the stuff from Ulysses into Scrivener. Scrivener is wonderful, but you need some time to really enjoy it. At the beginning it can be frustrating, but there is a pretty good introductory project enclosed. The documentation, however, is useless if you are new to Scrivener. Too many new concepts and terms. Once you get the hang of it, however, it magically turns into a remarkable thing which covers almost every nook and cranny of Scrivener. But I digress. Scrivener imports the folder structure and files I made in Ulysses, so I have the basic structure, and my rambling, as I require it. As you see below, there are still placeholders where anything elaborating the dour text will appear, and in Scrivener I’m actually doing it.
Things shaping up nicely, within Scrivener I can create links between documents, thus creating my glossary. It also creates an index, which is another necessity. Then it’s just fleshing out the bone, giving my mad ramblings from Ulysses more substance, whole sentences and a resemblance of grammar, all the things to make it readable.
Creating three separate projects would have been the next step, but I decided to start with the support staff documents and the employee documentation first. Both need to be way more elaborate and way easier to keep in sync. Which means, less work. The nerd stuff could wait.
There we are. Almost ready to go. From there, it’s just about setting up your export process, and you’re basically done.
Just kidding, that part is highly complex and mastering it took me quite a while. Once done, however, it was easy to create the different kind of documents I had in mind, PDF, ePub, and HTML.
PDF, because it is easy to create and even easier to distribute. It can be stored on a web-server for download for those not happy reading everything in a browser. Personally, I prefer eBooks. I’m working with Macs, iPhone & iPads all day, and every device has an eBook reader integrated. Having any kind of documentation on hand on any company device seems, to me, far better than having to either download PDF before you know you might need them or trying to access a web-server which you can’t because your VPN or whatever isn’t working. Just making sure there is nothing sensitive on the employees devices, is all. Deployment using the MDM-server is easy. And, of course, we should still have that intranet server, for which I did create the HTML version.
Once published, I use Scriveners snapshot feature to save the project’s state at publishing, adding my comment to it. Having that makes it easy to compare different versions if you need to. If you’re into collaborating with someone else, be aware that Scrivener is a single user app. While, technically, two can edit the same project-file, I flat out guarantee that it will, in the end, corrupt the whole thing. In that case, what I’d suggest is creating a project with the single purpose of sending it to the other author. If you have both projects open, you can simply select the chapters you want to send and use the Send to project command. They even keep their snapshot data with them. It works, for two people. More and you’d probably run into trouble fast, so: Don’t.
And there you have it. Ok, the actual writing took way longer than the setup did, but in the end I now have a working, stable system and in case of an update I just make the necessary edits the texts, upload the changed documents onto the server or push them to my devices using MDM.
