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 want to apologize in advance if my headline is not specific enough, but I think this is a general question, although I have a very concrete example:

In my team we maintain a test specification which we use every time we release software. The specification is written in Word and, as a consequence, we occasionally have compatibility problems, wrong formatting in some parts of the document and sometimes people use the heading levels incorrectly. Nothing major, but annoyances none the less. But essentially our specification consists of test cases which can be described simply as a headline with some numbered instructions.

I think we would be a lot happier with using a lightweight markup language (e.g. AsciiDoc or Markdown) since it would be sufficient to describe the content. We would have other concrete benefits (add it to git, use diff tools, easily convert to other formats, not needing Word).

This made me think - are there any advantages, in general terms, to expressing information in the simplest possible format?

share|improve this question
    
Personally, I try to use text based files in conjunction with version control whereever possible, but IMHO sometimes Word is not a too bad choice. To your example: what makes you believe people would use heading levels more correctly in AsciiDoc or Markdown when they are not even able to do this in Word? Moreover, I don't know any typical git client for Windows, but TortoiseSVN uses MS Word itself as diff tool when you compare different revisions. And "converting to other formats" - what other formats do you really need which are not supported by Word? –  Doc Brown Jan 4 '13 at 11:44
    
I am unsure if your general question is not too broad - "information" is a very broad term, and "the simplest possible format" a very subjective matter. –  Doc Brown Jan 4 '13 at 11:58
    
About the git clients - we use git extensively already (certainly more often than we use Word) so this is even one of the reasons why i think the git workflow will be faster. About the "other formats" - we considered making a nightly conversion to HTML for easy browsing but other than that i don't know... –  Vandhunden Jan 4 '13 at 12:39
    
My point is: instead of using something like AsciiDoc, did you seriously consider just to improve your Word based workflow? For example: try to add the Word doc to your git repo. Make yourself familliar with the diff functions of Word. Did you consider HTML conversion using Word, or use link references in Word for easier browsing? Not that I don't like AsciiDoc, but if you have non-developers editing your test spec, they might be much happier with Word than with a text-based format. –  Doc Brown Jan 4 '13 at 14:31
    
Do you mean "simplest possible format" == "wiki-like-plaintext" ? –  k3b Jan 4 '13 at 14:40
show 2 more comments

2 Answers

In a sense you answered your own question. There are a few main advantages of conveying the information in the simplest format possible:

  • Ease of transport (or portability)
  • Clarity
  • Searchable

What I mean by ease of transport is the ability to use that information in as many places as possible. Using plain text for instance gives you incredible portability from one system to another. However, without formatting it might not be as clear.

Clarity is where the information conveyed is easy to understand and get across. While using something like Word can make the information very clear through advanced formatting as soon as you need that information somewhere else, the formatting can get mangled or lost. Thus clarity is lost and a simple information format with transportable formatting helps.

Simple information formats tend to be more information dense. That is what information is recorded in the format is actually appropriate information rather than lots of meta information used to handle things such as formatting. This tends to make the information more searchable with better hits. Most systems can search Word text with no problem and this is rarely an issue these days, you will still get more bang for your buck searching through simpler formatted documents.

I prefer to use Markdown myself where possible. Most of our information is kept in a wiki for this reason where it is mostly just plain text and simple formatting markers. This makes the information searchable, clear, and portable.

share|improve this answer
    
And does your Wiki smoothly integrate into the version control system you are using for your source code? Ours (MediaWiki) does not, it has its own versioning mechanics, that's why we put software documentation typically not there - it is not "simple" enough for us. –  Doc Brown Jan 4 '13 at 11:55
    
This is the kind of answer I was hoping for. Just a comment about the wiki part - we considered this as well, but in our case we would lack something like a "tagging" feature... –  Vandhunden Jan 4 '13 at 12:19
    
@DocBrown we don't have our Wiki integrated into our version control system. It doesn't make sense for us since we prefer live editing and collaboration over versioned documents. However, different requirements for different groups so I understand this could be a problem. I was not specifically advocating Wiki in so much as answering the question on why simpler formats. For us our Wiki is infinitely easier to find stuff and simpler to use than our Corporate Sharepoint site. It has Word doc support but no one can find anything there. –  Akira71 Jan 4 '13 at 13:06
1  
+1 Examples are JSON, XML (HTML in particular) _ very simple and powerful at the same time. –  superM Jan 4 '13 at 18:42
add comment

To separate data from implementation.

The more simple the data format, the more flexible its use becomes. The more complex the data format, the less flexible and more susceptible it's contained data will be to bit rot.

Take database data. While it's possible to transfer the data in it's native format, that data will not be understood by any other system and, in some cases, different versions of the same system.

On the opposite end of the spectrum is CSV. It's practically ubiquitous for storing and transferring data in plaintext but the disadvantage of using it for database backups is you lose the structural rules.

Structure is useful too and, in some cases could be represented as it's own data format. For example, SQL stores database structure, CSS stores layout and design structure, config files store implementation structure, XML schemas store XML format structure, all of which use plaintext as the universal medium.

While not new, it's becoming more common to see data formats and even platforms (ex MVC) fundamentally designed to separate data and implementation. The reason being, data in it's true form is timeless whereas implementations are in constant flux. It just makes sense to store data in a format that presents the lowest barrier of entry to use in current and future implementations.

Even formats like Markdown present implementation specific issues but their simplicity makes them much easier to adapt than a more complex format (ex Word). Especially considering that the Markdown format itself is designed with conversion (ie to HTML) in mind.

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.