I’m currently an intern at a government contractor and am getting the (obnoxiously unavoidable) feeling that Word is the de-facto standard in the software development process.
Its binary format makes it very difficult to collaborate on documents in the way I am used to collaborating on a code base. The use of plain text markup (with such languages as LaTeX, Markdown, ReStructured Text, etc.) allows for a diff-friendly document that works well with the normal workflow of a developer. As for comments where the language doesn’t support them (eg Markdown), there are many existing solutions that allow collaborative comments on code bases (eg GitHub, Bitbucket) that could easily be applied to other plain-text files containing markup.
I understand the need to cooperate with technologically illiterate management necessitates some sort of graphical interface to everything, but such interfaces exist for most of these formats. For example, LaTeX has a ‘fork’ of sorts called LyX that puts a graphical front-end to a plain-text, LaTeX-like syntax. This file, even though primarily graphical in its editing, is still diff-friendly. (It even also has Word-style comments.) Many of these solutions could yet be used instead of Word, and the vast majority are free or open-source.
However, we use Word even for our own internal documentation that nobody else sees. We work with text for a significant chunk of our career—why is documentation so special? Aside from the trivial “We didn’t know any better and now we’re stuck here”, there must be reasons supporting such a decision. What challenges face the software development process in using plain-text documentation in lieu of other, more colloquial (and debatably less powerful) means of writing documents?
Since the reasons will differ, perhaps answering for these two closely related scenarios separately should be in order.
- Using plain-text documentation from the start
- Migrating to plain-text documentation over time
11
Lots of participants in the software development process are not developers, and need the ability to interact with documentation regardless. Should QA/Marketing use word and developers use something else completely? It would be inconsistent, it would add another tool into the maintenance chain and the IT portion of a company may have no idea what to do with the files, when they know completely well how to manage/maintain a word document store.
Above all else, many non-developers have spent years in university using Microsoft Word to turn in their work, frequently having had actual training classes in just how to use word. They know it far better than alternatives. I can hardly tell the difference when I’m working in Open Office vs Word, but when I had my sister in law use it to save money, a week later she had her husband buy her Word and proclaimed “Since I got word I love my new laptop!”. Think about the mindset that conflates things like that, a slight change in what they’re used to is not ‘slight’ to them.
Modern word allows version differences, annotations with version tracking and change merging as well. It may not be as straight forward as merging code is, but I’ve seen many project managers do it easily, so surely devs can manage to do it too.
Beyond that, it has become quite common amongst dev teams to do documentation in wikis because it does get back to the textual representation while staying simple enough that non-developers can make edits.
6
Personally I think it’s an issue of education.
Most people have been tricked into thinking that using a tool like MS Word makes it easier to produce quality documents, but from what I’ve seen it actually makes it harder. You end up having to debug formatting endlessly and fight your tools to get the result you want.
Tools like Scrivener allow you to get a bit closer to the reality of the document without having to fight it like you do with Word. Partly because of the realisation the WYSIWYG doesn’t actually work very well.
In my own organisation the more people I move to using MarkDown for most of their document needs the more people are happier and more productive.
3
You really have 2 questions:
First: Why do non development groups not use LaTeX or other Markdown in the software development process?
The problem with migrating to LaTeX is the perceived learning curve particularly when you are dealing with non technical users. Users already know other formats and don’t want to have to learn another method of doing the same thing they been doing. They know little if anything about how to diff 2 documents and so there is little value in changing to a text based format for them. Explaining to a person that you have a solution for a problem they didn’t know they had is a pretty tough sell.
You also can’t underestimate the value of forward momentum. In order to migrate to a new format you really have to convince other people in your chain it is a worth while to investment in learning something new. Even if you don’t expect them to edit anything It takes time and a lot of effort to migrate to a new format when an existing format works (even if poorly).
The second question: Why does my team continue to use word documents when there are better options and they are more than capable of learning them?
This is something that you should talk with the people on your team about. There may be valid reasons that they choose to maintain word documents or it may just be because that is the way it has always been done.
There are costs associated with any change and it can be expensive and time consuming to move hundreds or thousands of documents to a new format. If you are going to try to change your environment expect to have to make a case for why you should change
3