A new feature in Dynamics AX 2009 enables developers to write developer documentation directly in the X++ Editor while writing the production code. The feature is very similar to the XML documentation feature in C#.

Basically any method can contain /// (triple-slash) comments followed by structured documentation in XML format. Here is an example:

The developer is assisted by a dynamic documentation template, which is inserted through an editor script. The template automatically builds a skeleton including all the required tags for the current method. On top of this the written documentation is validated by best practice rules; which effectively prevent the documentation from growing stale. Finally a tool enables extraction of the documentation, so it can be processed outside AX, e.g. for publishing on MSDN.

But who really cares about this? Great tools won't make my day - I want documentation!

Dynamics AX 2009 contains about 125.000 table and class methods in the SYS layer. To give a perspective on this number, it will take you over 15 years to document them all, if you can document 5 methods an hour.

All the methods shipping with Dynamics AX 2009 will have some documentation:

10% will be available in the X++ source code, in the product documentation and on MSDN. This content has been written by developers for developers. (and reviewed by Content Publishing).

20% will only be available in the product documentation and on MSDN. This is pattern matched documentation for methods such as main(), construct(), pack(), unpack() and parm(). This documentation has been written once for each pattern, and then applied to all methods matching the pattern.

70% will only be available in the product documentation and on MSDN. This is automatically generated minimal documentation for methods that we haven't manually documented. It contains syntax and other high level information.

Or in other words:

You will never see the dreaded boilerplate "At the time of publication..." again.

“How can it be”, I wonder out loud, “that our projects always finish on time with a little less functionality than we anticipated?”

“As far as I understand, it is no wonder that your projects finish on time, as you have a fixed delivery date. At that date you basically ship what you’ve got.” Søren answers and sips his wine.

“Well, shipping is a big word. After the development phase we go into a stabilizing phase which can be long and demanding. We really need these fixed dates, as our customers expect us to deliver on the date we announce. ” I feel myself already in defense, and I try to steer the discussion in the direction I want it to go, “What I struggle to understand is, that even when we start out with the best intentions, we always end up cutting functionality away.”

“Ok,” Søren replies, folds his hands, and looks at me, “this is as good a topic as any. Let me hear how you figure out how much you can do within the development phase.”

“First of all we have a planning phase with a long list of features and functionality that we would like to implement. This list is based on customer feedback and market demands. As you might expect the list is so long, that even with all developers in the world and an undisturbed decade, we wouldn’t be able to get to the bottom of it.“ I exaggerate to drive home my point, ”The list is then prioritized, and the developers are asked to give estimates for the top items on the list.”

“So at this point you have already trimmed the list of features?”

“Yes, at this point we have a net list of features. The developers go away with this list, and do their magic; you know, prototyping, designs, specifications, and so on. Then they come back with estimates. With the estimates in hand we can derive a plan. Typically this includes trimming the list of features even further. We end up with what appears to be a realistic plan. We often leave a few more features in the plan than the estimates allow for, just in case a feature is finished early.”

“Do you have reason to believe your developers over-estimate?”

“No, on the contrary. If they were giving too long estimates the features would have been cut early, and we wouldn’t have this problem; where we cut features as we run out of time."

“So do you believe your developers under-estimate?”

“I have no reason to believe so. They have been doing this for so long, and are really a great team, and they have a remarkable tendency to hit the right dates. Having said this, they do miss the dates occasionally. “

“And what happens when they slip?”

“Well, since they set the initial date. It is their responsibility to catch up. Typically they do overtime to get back on track.”

“And when they don’t succeed in catching up?”

“Then we have a problem and have to cut features from the product. Which is my headache – why can’t we implement according to our plan?”

Søren is quiet for a moment. I use the pause in the discussion to refill our glasses.

“Let me ask you this,” Søren says, “Suppose I asked you to paint my house. You can take as long as you like, but you need to tell me up front how long it will take. If you are not finished by the time you promised me, you’ll have to pay me a compensation for each minute you are late. How would you estimate this painting project?”

“When you put it like that, I would naturally build a lot of safety into the estimate, so I’m certain I can finish well before time. I just wish that my developers could finish on time!”

“Do the rules your developers play by resemble this scenario?” Søren asks.

“Thinking about it, their behavior does, but the outcome certainly doesn’t. They are not finished well before time.”

“That is because building software is different from painting a house. You know you are done when the last board has been painted. That is not true for software. There is always something more you can do. Adding more comments, writing more tests, refactoring, just to name a few. This is the developer’s baby; they want it to be as perfect as possible before passing it on. When they finish before time, they will spend whatever time is left polishing it off.”

“I know, I was a developer once”, I smile, “and I’m fine with that. Delivering polished features sounds good to me. The problem is we end up cutting some.”

“Let us look at the painting project again. Regardless of how conservative your estimate is, you may get surprised: the foundation might not be in the condition you expected, you may run out of paint, the ladder might break, and the brush might be too small, and so on. Regardless of the precautions you take real life can and will play tricks on you.”

“Yeah, we have all been visited by Murphy.”, I smile.

“The only sane way to deal with it is to include variation in the planning of the project.”

“Hang on a second. “, I have to digest what I just heard, “Are you saying that whenever we finish a feature early it doesn’t mean the next feature will start early – and whenever a feature is late it delays the rest of the plan?”

Søren is silent. I shuffle my feet, feeling awkward. After what seems like a too long pause, I say, “I think you are right; even when we build in a safety buffer into all our estimates we run out of time. What else is there to do?”

“How about delivering even more features on time?” Søren takes a pen from his inner-pocket, leans forward and grabs a napkin. This is what he draws:

“Basically this is what you currently do. Each feature is protected from variation by the buffer your developers build in to avoid working overtime. Suppose you remove the buffer from each feature, and add a buffer in the end instead. It probably has to be somewhat larger than the buffers you use today. Something like this”, Søren continues to draw.

“I see the point. This way each feature will commence as soon as the previous is done, and any variation might be caught up during the project, and if not we have the buffer in the end.” This feels good, perhaps too good to be true; napkin-drawings and red wine have a tendency to simplify things. After a short while I’m able to put words to what disturbs me, “this would mean our developers have to give shorter estimates. I don’t want to go onto their turf, questioning their work.”

“Well, you don’t have to”, Søren answers, “you have to ask for estimates differently. Instead of asking ‘When can you be finished?’, ask ‘When can you be finished with a 50 percent probability?’ The word estimation intrinsically holds a probability factor; you have to get that information for the estimate to be of true value.”

Being a tech-guy I cannot help myself questioning something as scientific as a number, “Why 50 percent?”

“First of all it tells the developers that it is perfectly alright to be late, actually you anticipate half the features will be late. This way you reassure the developers that it doesn’t mean they have to work extra hours if they are late.”, Søren sips his wine, ” Secondly, it also means half the features are early. This way there is a good chance of the late features being balanced out by the early features.”

Søren draws again.

“If you try this out, you’ll be surprised at how short the new estimates will be. In theory a 90 percent probability estimate is about twice as long as a 50 percent estimate. But to get such short estimates your team needs insight into this way of planning. And the plan has to be transparent. Your developers will need this insight to understand the importance of letting go of a feature once it is completed; instead of keep polishing it and delaying the delivery.“