The other day, someone asked me if it were against agile-lean principles to create a software description document. What a question. I can't believe that anybody would tell you that creating anything is completely against principle in every possible situation. I suppose there are those who might say that such an artifact might be waste in the majority of situations, but I think it's possible you might find yourself in a place where creating a software description document is vital to the delivery and maintenance of your product.

I can't imagine such a situation, but I wouldn't outlaw it out of hand.

I have a little suggestion: next time you're wondering about one of these kinds of things -- creating an ERD, documenting a peer review session, writing an allocated baseline -- instead of accepting it as a task, treat it as a requirement. I suppose you could then stick it into the backlog and prioritize it, but what I really want you to do right now is put it into the form of a user story. Figure out who is benefiting from the value generated by this feature you want:

As a standards auditor,
I would like a software description document
So that new software engineers can ramp up quickly.

That's just my suggestion for the description document. So let's take a look at that value (the so that) and user (the as a). They're disconnected, aren't they? How does the standards auditor benefit from having new engineers ramp up quickly? Aside from their general patriotic self-satisfaction, they really don't. And if they did, is the benefit of standards auditors valuable to our customer in any way? I don't think any auditor would really say that they should be the beneficiary of any software effort. They'd probably tell you that the as a should be the team or maybe the new software engineer.

Let's say that's true. I think it's valid to do stuff that's valuable to the team to get its job done efficiently. So you could take this user story, present it to your team, and the team could add software description documents to their working agreement.

But don't do that yet.

If you were a scrummaster and your product owner presented a user story shaped like that, what would you say? I'd say, "Hold on a sec, Bucko. That's not a what; that's a how." There's a whole lot of assumptions going on in there. The first two off the top of my head are that a) it's going to be necessary for this product and this team to have a mechanism to on-board new team members frequently and b) the document is the best way to achieve that. I'm curious how many developers who join a team really like to start by sitting down and reading a document. My experience is that they like to dig around in the code. I know I do.

At any rate, we need to figure out what the feature we're looking for really is. Here's a suggestion:

As a high performing team,
I would like a way to quickly familiarize new team members with the product code
So that we are not slowed down by the one new member we'll get every six months.

What's the best way to meet this requirement? I leave that as an exercise for your team to figure out. Feel free to brainstorm in the comments.

Insert all the normal disclaimers about doing what you have to do to meet regulatory, legal and other constraints. This is just a suggestion for thought...

2
thoughtful messages from friendly readers:

"So that we are not slowed down by the one new member we'll get every six months."

There will be a learning curve, and there will be a tax on existing team members. I consider that to be a given. I guess I would consider the goal to be to find the most efficient way for the team to integrate the new resource - efficient being measured by removing the most points from the backlog, I guess. I don't know this stuff as well as you.

I've been in many situations where I've had to get up to speed on a new tool or new piece of software. In both cases, I think the most efficient way for me to come up to speed is a combination of self-study and having a subject matter expert available. Self study generally means studying the code. My experience with documents is that they may have been correct at a point in time, but their accuracy is always suspect. So even if I had a document, I wouldn't know how much I could trust it. Studying code frequently involves studying the calling sequence, so any automated tool that can show me the calling sequence based on the existing state of the code is helpful.

However, in the process of self-study of code, I take notes, and I sometimes create diagrams and other artifacts. I find that the act of creating those documents for myself helps with my study. I have some that I created seven years ago that sit in a binder near my desk, and when I serve as the subject matter expert for another developer, I take them out and reference them.