Who needs documentation anyway?
So, we have a dilemma at work. How do the developers and documentation teams
collaborate on a single set of documentation files while using familiar tools?
Is such a thing possible or am I dreaming?
Currently the documentation team at our work uses Author-it, a full-blown authoring 'solution'. For some time we, the developers, were been sent Word documents which we updated and emailed back. At this point the source control fanatic in me started to twitch. It's a document - just like source code - can I see who did what changes? How do two people work on the same document at the same time, and what about conflicts? Can I have multiple version of the same document? The other problem was one of cost; Author-it is too expensive to justify individual licenses for developers.
We had talked about switching to a more text-based documentation system on-and-off for some time. Finally I cracked and decided to just do it.
Latex was the first possibility that surfaced. However, as I thought about it more the idea of everyone having to learn obtuse Latex syntax before writing a single-line of documentation was a little off-putting. Note: I really do like Latex, but I felt like it might have been overly complicated for our situation.
The second alternative was to use a publication format like Docbook or DITA. While certainly a powerful way to group content, the prospect of living in XML hell didn't enthuse me all that much. I already get enough of that in Java-land thank you very much.
My final option was to use a lightweight markup langague, like Markdown or reStructureText (ReST), which GitHub actively promotes for their README files. This felt like the right fit for us, and without further consultation I converted our current internal word documents to ReST, added them to Git and created a Jenkin job to output PDF and HTML files. Bam!
At this point us developers were happy again. We were back to using our favourite source control for collaboration, without have to stuff around with emailing Word documents. We could quickly edit text files, use source control to track/merge changes and didn't have to worry any more about niggling presentation issues. My manager, on the other hand, who was away at the time, was not so pleased. (I swear this had nothing to do with the timing of my rash decision).
For us developers the idea of using a text editor to edit a document is a fairly comfortable one. For people used to - and who enjoy using - Word this was in some ways a big step backwards. No spell checking, no auto-complete, no drag 'n' drop. All that good stuff. Another complaint he had was about presentation - the PDF output wasn't slick enough to be used officially. Finally, if we wanted to switch to something else, ReST seemed to lack in some of the more powerful concepts required to support single-source publishing.
I could definitely be wrong but it feels like nothing has quite nailed this space in the space, at least in the OSS community. What would certainly help is a powerful and easy to use editor. Perhaps a plugin for Open Office would do the trick? Alternatively a browser-based editor, not too unlike this.
We're currently in a holding pattern at the moment. Developers are still (happily) using ReST, but the 'official' stuff is being written by the documentation team. Us and them.
I see a couple of available options:
Currently the documentation team at our work uses Author-it, a full-blown authoring 'solution'. For some time we, the developers, were been sent Word documents which we updated and emailed back. At this point the source control fanatic in me started to twitch. It's a document - just like source code - can I see who did what changes? How do two people work on the same document at the same time, and what about conflicts? Can I have multiple version of the same document? The other problem was one of cost; Author-it is too expensive to justify individual licenses for developers.
We had talked about switching to a more text-based documentation system on-and-off for some time. Finally I cracked and decided to just do it.
Latex was the first possibility that surfaced. However, as I thought about it more the idea of everyone having to learn obtuse Latex syntax before writing a single-line of documentation was a little off-putting. Note: I really do like Latex, but I felt like it might have been overly complicated for our situation.
The second alternative was to use a publication format like Docbook or DITA. While certainly a powerful way to group content, the prospect of living in XML hell didn't enthuse me all that much. I already get enough of that in Java-land thank you very much.
My final option was to use a lightweight markup langague, like Markdown or reStructureText (ReST), which GitHub actively promotes for their README files. This felt like the right fit for us, and without further consultation I converted our current internal word documents to ReST, added them to Git and created a Jenkin job to output PDF and HTML files. Bam!
At this point us developers were happy again. We were back to using our favourite source control for collaboration, without have to stuff around with emailing Word documents. We could quickly edit text files, use source control to track/merge changes and didn't have to worry any more about niggling presentation issues. My manager, on the other hand, who was away at the time, was not so pleased. (I swear this had nothing to do with the timing of my rash decision).
For us developers the idea of using a text editor to edit a document is a fairly comfortable one. For people used to - and who enjoy using - Word this was in some ways a big step backwards. No spell checking, no auto-complete, no drag 'n' drop. All that good stuff. Another complaint he had was about presentation - the PDF output wasn't slick enough to be used officially. Finally, if we wanted to switch to something else, ReST seemed to lack in some of the more powerful concepts required to support single-source publishing.
I could definitely be wrong but it feels like nothing has quite nailed this space in the space, at least in the OSS community. What would certainly help is a powerful and easy to use editor. Perhaps a plugin for Open Office would do the trick? Alternatively a browser-based editor, not too unlike this.
We're currently in a holding pattern at the moment. Developers are still (happily) using ReST, but the 'official' stuff is being written by the documentation team. Us and them.
I see a couple of available options:
- What am I talking about, emailing Word documents around is fine - stop complaining.
- Embrace Author-it and see if it can support more collaborators. Just looking at their website briefly it seems like they have an online review mode.
- Meet my boss half-way, he can live without the nice GUI but we switch to a singe-source markup language like DocBook/DITA.
- Everyone else be damned; developers rule; reStructuredText it is!