What are the best possible instruments/tools to maintain an SRS in a small agile project (up to 10 people)? How to keep this document(s) available to the entire team, to enable its baseline (and re-baseline), version control, etc. What is your recommendation according to industry experience?

  • Did you look at ScrumWorks from CollabNet? It's free for upto 10 users :)
    – PhD
    Dec 8, 2011 at 21:55

4 Answers 4


The best way to document code is to write self-documenting code. This way, the desired behavior of the code is always kept with the actual behavior of the code, and - fingers crossed - they become the same thing.

Unit tests and automated acceptance tests, aka examples and scenarios, can form another part of this living documentation. All these should be checked in alongside the code.

However, sometimes it can be hard to see the big picture from code and tests alone. Keeping lightweight documents describing the capabilities and architecture of the system on a wiki might also be an idea. Some wikis - for instance, Moin Moin - are small enough that they can be checked into version control alongside the code. This high-level domain knowledge doesn't change as often as the code, though, so checking it in isn't as important.

Some project tools can keep histories of features, stories and bugs. A stack of index cards is almost as good at doing this as an expensive electronic tool, and has many other benefits around visibility, team ownership, etc.

The most important documentation, and the one which will affect the project most greatly, is the documentation in people's heads - their experience, tacit knowledge and understanding. To keep this documentation alive and maintained well, make sure everyone talks about the project and shares that knowledge frequently. Tell stories. Pair program. Make sure the project team members are happy and motivated so that they stay, keeping their documentation accessible for newcomers.

  • 1
    While I agree with your first sentence, I think it's a little misleading to say the best way to document code is with self-documenting code when the question is about best ways to maintain an SRS. SRS's oftentimes target both non-technical as well as technical users, so it might not be clear to inexperienced developers and PM's that you're referring to two separate audiences. Other than that, I agree 100%.
    – jmort253
    Mar 7, 2012 at 2:48

Scope Management across a team is easiest when the team knows they share the same vision for WHY they are building the software. Given a shared vision for Why, it becomes easier to describe HOW you are going to get there. I like the Lean Start-up approach that combines an Agile Software Development model with a Customer Development Model. This approach helps blend technical feasibility with business viability and customer desirability. Given a shared understanding of WHY and HOW we are building solution then the scope management process becomes easier and lighter. Without that shared understanding, scope management becomes an inventory management process and not an unfolding process.

I try to find the lightest way to manage stories and I try to make sure that we progressively elaborate them in a just in time basis. I like to work with a board or product that can allows the team to create story maps. Typically, I map the Epic stories that comprise our believe of the Minimal Viable Product or Minimal Marketable Feature on the wall for the team. It is important to have a team of 10 see and be a major part of how the stories are unfolding from real customer/user feedback. You can use a wiki or a idea management system to link those customer narratives to your stories management approach. I am partial to Rally's solutions for story management for small teams including Community Edition - free for 10 users or Agile Zen free for personal accounts. If you want a very detailed and prescriptive approach for Agile Requirements Management, don't miss Dean Leffingwell's newest book of the same title.

Like Lunivore, I believe the flow of knowledge is the most important thing to stimulate. Creating the right software, based on successful prototypes and tests, as it is typically more important in the early going than building the software right. As you understand the problem domain and the solution begins to emerge, building software right becomes just as important. Thus as stories get implemented, writing simple well document code with unit tests help describe the functionality for the rest of the technical team. Continuously deploying that code is almost as critical for keeping the flow of knowledge from Agile Development to the Customer Development team during the unfolding process.


The answer depends on the use case.

If the spec is part of a larger project then you're probably going to have to link the SRS requirements to parent requirements in a higher-level spec. The best way to do this is with custom built tools that are designed for requirements management and traceability. DOORS is a standard in the Aerospace and Defense industry (and potentially others as well, but I don't know about them).

However, it's a custom and specialized product and it can take significant effort to procure, properly configure, maintain, etc. It requires training and super users to extract the full functionality and thus is probably pretty expensive. If you really need this type of a solution it's available, but honestly it sounds like you don't.

If the spec is stand-alone and/or the project is small (which sounds like your situation), then I suggest a lower-overhead method. Try storing the content of the text in a plain text file and using your version control system (VCS) for configuration management. I see several benefits of this approach:

  • you are writing software, so your developers should already have a VCS that they know how to use and like
  • plain text files are easily diffed so it will be easy to see changes as the requirements evolve and mature
  • plain text files can be easily merged, so several people can be working on the document at the same time; this is especially true if you have enough of an organization structure on your team and in the document to prevent people from simultaneously editing the same sections of the file
  • because text files don't support it, your people will be less inclined to spend time doing non-value-added work like formatting the spec to make it look pretty

Now the last benefit is also the biggest downside: text files are relatively ugly when they're printed out. If this is going to be a problem for your team (e.g. you need to deliver the spec to a customer or post it to a website and want it to look pretty), then have one of your devs write a script or something that operates on the raw text file** and outputs something with the necessary formatting in a format like html, pdf, or docx. You can store this script in the VCS as well, so between the script and the text file(s) you can lock down not only the content but how it looks in final layout.

** One obvious option here is to write the script in Markdown--the same mark up language used on Stack Exchange. Then you just have to run your text file through a Markdown parser and feed it up with some CSS.

  • In regards to the downside, that seems like a lot of work not done on the project just to support the project, especially when there are out-of-the-box solution that let the team focus on the project instead.
    – jmort253
    Mar 7, 2012 at 2:51
  • @jmort253 True, but the script is one-time development and then maintenance and having it in house means you can make it look just like you want. Not to mention there are cheap tools that can turn markdown into HTML. And that cost has to be weighed against the cost of the out-of-the-box solutions. DOORS costs a fortune and the labor to administer it is an expense as well. I worked on a program with 3 full-time DOORS admins who didn't even write requirements, just did meta-work in the tool.
    – Adam Wuerl
    Mar 8, 2012 at 1:56

Based on my experiences, user story works best. We use it as acceptance tests too. User story must be understand by both technical and business (non-technical) side, in that order we create user story together with our customer.

  • William, can you say anything about how to keep user stories maintained, as things go in and out of scope? I didn't cover it in my answer and it would be a useful addition.
    – Lunivore
    Oct 21, 2012 at 11:06
  • My team use a versioning control system and we are check in the user stories file there. That way we are able to track changes. Nov 27, 2012 at 12:36

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.