Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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
share|improve this question

closed as primarily opinion-based by MichaelT, GrandmasterB, Snowman, gnat, Bart van Ingen Schenau Dec 3 at 11:40

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

2  
for independent reasons it might be wise to migrate to newer versions of word (office 2007 / 12.0 and higher) whose document formats are based on xml. up-to-date versions of openoffice and especially libreoffice might be an even better choice - import/export filters allow seamless integration with a ms word-based workflow. more to the point, working with markup languages in pagesetting demands a higher level of abstraction and better structuring of ideas beforehand while not easily supporting exploratory writing. and of course the ms office ui is customary - no training required. –  collapsar Jul 17 '13 at 15:20
2  
I'm not sure I agree with your premise - I'm sure there are plenty of places which one or other of the markup languages, because of the benefits you describe. –  Baqueta Jul 17 '13 at 15:30
1  
As collapsar pointed out, XML based word docs are very easy to program for (openxml sdk,... (I can advise the ClosedXML and Novasoft.DocX for c#) When coming from an academic background TEX may seem great, but if no-one uses it, it's as good as dead. The learning curve is way too high! Your mother and grandmother probably know what word is. Ask them about TEX, I'd be surprised! –  Mvision Jul 17 '13 at 18:01
1  
And as far as the UI being intuitive, this is true for a good chunk of the cliche-level-of-normal workflow, but breaks down for anything more complex. See superuser.com/questions/620454 and also note that the way to update a TOC is to insert a new one in the middle of it and wait for the popup. The way to persistently ignore spelling for a chunk of text is to set the language<-null. Is any of this intuitive? But this is besides the point. Plain-text completely exposes the structure and content of the document; no mess, no fuss. –  Sean Allred Jul 17 '13 at 18:09
1  
@rath Absolutely. If anyone is hoping to bring some young minds to the dark side, the comments/answers to the linked should help get you started. (Especially Jubobs' presentation --- he uploaded an archive of it and it's very good.) –  Sean Allred Jul 23 '13 at 22:54

3 Answers 3

up vote 43 down vote accepted

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.

share|improve this answer
7  
I partly don't agree with your second paragraph: Most people I work with have no idea whatsoever about how to use Word and stuff. And feel generally uncomfortable with anything that doesn't resemble something they know (ribbons anyone? ;-) ). This means one could enforce anything on them. The rest sums it up pretty well unfortunately. –  nietonfir Jul 18 '13 at 11:44
    
@nietonfir wow, It's been my experience that word is every PM and QA persons favorite (read: only) tool –  Jimmy Hoffa Jul 18 '13 at 15:07
4  
@JimmyHoffa It is, but most don't know how to properly use Word (e.g. index, picture subtitles, first page headers, numerations, headings, …). –  nietonfir Jul 19 '13 at 9:35
2  
@JimmyHoffa: Yes, but how much training did they get for it? And how much of Word's functions do they really use? IMHO most of these user could easily switch to WordPad. –  Martin Schröder Jul 20 '13 at 20:45
    
Oh hi, @MartinSchröder :-) As for WordPad, while most of the content writers may not know how to use MS Word to its full 'potential', a few of them do. From my experience, it is a small set of power-users who set up a document (over and over again) for the users who actually add the bulk of the content. When someone wants to add a figure, a comment is added. (Maintenance of the document as a document, then, becomes at least a part-time job.) –  Sean Allred Jul 28 '13 at 13:30

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.

share|improve this answer
    
Are you really suggesting that it's easier to "debug" LaTeX than MS Word? –  immibis Dec 3 at 0:28
    
@immibis LaTeX3 knows this is a problem (even LaTeX2e, but it failed to get the point across). Ideally, there is no coding done on the document level (exposed to the author). All of the 'debugging' is done on the code level, where you have people who are familiar with the language do that work. Trust me, expl3 error messages are much more helpful :) –  Sean Allred Dec 3 at 0:32

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

share|improve this answer
1  
this doesn't even attempt to answer the question asked, "Why aren't plain-text markup languages (like LaTeX or Markdown) more popular in the software development process?" –  gnat Dec 2 at 20:26
    
+0, but agreed - this would be more appropriate as a comment. –  Sean Allred Dec 2 at 21:00
1  
After the question's first edit, it has become much better. @gnat, another look is in order. –  Sean Allred Dec 3 at 2:21

Not the answer you're looking for? Browse other questions tagged or ask your own question.