34

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
Improve this question
11
  • 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. Commented Jul 17, 2013 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. Commented Jul 17, 2013 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! Commented Jul 17, 2013 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. Commented Jul 17, 2013 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.) Commented Jul 23, 2013 at 22:54

3 Answers 3

Reset to default
43

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.

Improve this answer
6
  • 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. Commented Jul 18, 2013 at 11:44
  • @nietonfir wow, It's been my experience that word is every PM and QA persons favorite (read: only) tool Commented Jul 18, 2013 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, …). Commented Jul 19, 2013 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. Commented Jul 20, 2013 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.) Commented Jul 28, 2013 at 13:30
5

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.

Improve this answer
3
  • Are you really suggesting that it's easier to "debug" LaTeX than MS Word? Commented Dec 3, 2014 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 :) Commented Dec 3, 2014 at 0:32
  • @immibis It is in fact easier to "debug" LaTeX than MSWord. There are formatting quirks in MSWord which cannot be fixed by anybody without modifying the program MSWord itself. In those cases you can take all the time you need to learn LaTeX -> TeX -> C -> Assembler however deep you need to go. I do know users outside the software development field who have a good working knowledge about LaTeX and things like pstricks. They pick LaTex over Word every time. They usu. don't do a lot of complex debugging, they just ask somebody for help, which for them happens more infrequently than with MSWord. Commented Nov 24, 2018 at 23:39
0

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

Improve this answer
3
  • 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?" Commented Dec 2, 2014 at 20:26
  • +0, but agreed - this would be more appropriate as a comment. Commented Dec 2, 2014 at 21:00
  • 1
    After the question's first edit, it has become much better. @gnat, another look is in order. Commented Dec 3, 2014 at 2:21

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.