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. (Inception comment: it 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?

share|improve this question
1  
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
1  
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
    
They know what a text file is. Going through the TeXbook has taught me that literally any 'format' (eg markdown) can be TeX'd. Thus, the learning curve (even though I never noticed one with LaTeX) is moot. –  Sean Allred Jul 17 '13 at 18:05
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
show 6 more comments

2 Answers

up vote 41 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
1  
Hit the nail right on the head. –  Stargazer712 Jul 17 '13 at 15:36
4  
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
3  
@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
1  
@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
show 1 more comment

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
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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