There was an interesting debate on the Stack Overflow podcast regarding the value of software documentation. On one hand, organizations always think they need more of it. On the other hand, programmers typically hate writing it and usually think it’s worthless.

Who’s right?

The Problems with Docs

The real problems with software documentation for large internal applications is threefold:

• Small Audience: You may write the most beautifully detailed document in the world, but odds are it will only be skimmed and never actually read. As we all know from Steve Jobs famous quote “No one reads anymore”.  If people don’t read normal books by popular authors, are they really going to read your dry 20-page detailed software doc?
• Already Obsolete: When programmers start new projects, they typically don’t read the documents because they assume they are obsolete, and most of the time they’re correct. By the time the massive doc is finished, the software has often already changed by 20% and the screenshots need to redone.
• Great Programmer != Great Writer: Great programming and great writing do not necessarily go hand in hand. In fact, some people get into programming so that don’t have to communicate with anything other than a compiler. There’s nothing wrong with that, but don’t expect your programmer to write the clearest software documentation.

So, given that we’re up against all of this, is there any hope for software documentation?

The Bare Minimum

There are some types of documentation that add real value to a project. Let me list those and then talk about style:

• Scope Doc: In some form, you need to document what you’re going to build. Now, I’m not advocating a 200-page waterfall-style spec doc. But I’m saying that everyone has to be on the same page with what is being built and a scope doc is the best way to do that. Mockups using something like balsamiq are a nice touch in a scope doc as well. Spolsky has the canonical post on writing scope docs.
• Install Guide: The install guide has two functions: 1) It tells new developers what they need to install to get the project running, and begin development on it 2) It also helps the IT staff know how to rebuild the app if the server dies. This doc would typically include items like location of source control code and third party apps to install.
• User Guide Inline Help: Instead of a user guide that no one will read, implement some sort of inline help in your software application that appears right where the user needs it and helps them understand their specific problem.

For each of these docs, they need to be light: 5 pages or less, and heavy on bullet points, images and sub headings. The bottom line is that people don’t read anymore; they skim and software docs need to accommodate this fact.

Rule 1 of writing software for nontechnical users is this: if they have to read documentation to use it you designed it wrong.  

–Eric S. Raymond

Photo by Matti Mattila

Recently, I’ve had the opportunity to actually begin using Microsoft’s LINQ (language-integrated query) in a few “real” projects. So I’ve tried to spend some time actually understanding it rather than just copying examples.

Throughout this process I’ve gleaned a few key concepts:

1. Determine which LINQ you will use

One of the confusing aspects of LINQ is that it comes in five flavors:

• LINQ to XML: Used to query XML documents. Can be used in place of XPath or DOM manipulation.
• LINQ to Objects: Used to query object collections. Can be used instead of looping through the collection.
• LINQ to SQL: Basically an ORM (Object-Relational Mapper) used to map classes to DB tables and query them in code. Can be used in place of another ORM.
• LINQ to Dataset: Used to query datasets. Can be used instead of looping through a dataset or using the filter method.
• LINQ to Entities: Used to query conceptual database models rather than the strict table to class model that LINQ to SQL uses. Based around Microsoft’s Entity Framework.

Once you know which one you’re after, it makes looking online for examples much easier.

2. It’s all Extension Methods on IEnumerable

Here is the key thing to know about LINQ. It’s primarily a set of extension methods to IEnumerable. Extension methods allow you to add new methods to existing classes.

So if you want to start using LINQ just add a reference to System.LINQ and look at the intellisense on an object that implements IEnumerable. You’ll see a bunch of new methods like: Where, Order By, and Select. These are the core LINQ methods.

3. Prefer the Method Syntax over the Query Syntax

LINQ let’s you write queries using two different methods – the method (or dot) syntax and the query syntax. Here is an example of both:

     //Query Syntax
       var queue = from q in dc.SomeTable
               where q.SomeDate <= DateTime.Now
               orderby (q.Priority, q.TimeCreated)
               select q;
   //Method Syntax
        var queue2 = dc.SomeTable
             .Where( q => q.SomeDate <= DateTime.Now)
             .OrderBy(q => q.Priority)
             .ThenBy(q => q.TimeCreated);

When starting out, I think it’s MUCH easier to begin with the method syntax. It just makes more sense to a seasoned .NET developer and it doesn’t get confused with long-held SQL knowledge.

At the end of the day, the query syntax gets compiled into the method syntax anyway.

4. Understand Deferred Execution

In LINQ query execution is usually deferred until you request the data. So, consider the following example from Patrick Steele:

  string firstLetter = "B";
   //Query NOT run here
   var query = from c in customers
               where c.Name.StartsWith(firstLetter)
               select c;


firstLetter = "J";
   //Query actually executes here
   foreach (Customer c in query)
   {
       Console.WriteLine(c.Name);
   }

The query doesn’t get executed until it is actually used – in this case in the foreach. The implications are that the “J” filter is applied to the above code rather than the “B” filter.

5. Learn Lambda Syntax

You can’t get away from Lambdas if you use LINQ. Basically anytime you use the “Where” statement you will need to use a Lambda. A lambda is just a fancy name for an inline function with a specific syntax. You’ll know that you need to use a Lambda, if you see “Func” in intellisense. Here is an example of a lambda:

 .Where( q => q.SomeDate <= DateTime.Now && q.Locked != true )

This snippet says that q (which is just an arbitrary parameter) should be filtered by the SomeDate and Locked properties. It is equivalent to a function that takes a parameter called q and applies the filter. The only difference is that it’s all written inline.

I hope these five tips help you in your journey to use and understand LINQ!