My background is 6 years in managing "normal" projects in an outsourcing company. Recently I've joined a Scrum project.

Here I see people not doing any documentation, no SRS (Software Requirement Specification), no Detailed Design, almost no documents of any sort. They only create some user stories, then start to code. They don’t even create a database design but do “code-first” and generate the database from code.

So, the question is, how can you maintain such a codebase after the project is “done”, say 3–5 year later, when all the current team members have moved on or can’t remember what they did today?

  • 1
    Agile frameworks are all about emergent design. If you want to know if the code is maintainable, hire an outside person for a few weeks to solve a minor problem to see if the project is adequately documented and reasonably maintainable.
    – Todd A. Jacobs
    Dec 21, 2017 at 16:53
  • 1
    “Code-first” doesn’t mean what I think you think it means. It just means that the design is encoded in the general purpose language the rest of the software is written in, instead of being encoded as SQL DDL (data definition language).
    – RubberDuck
    Dec 24, 2017 at 17:38

3 Answers 3


Some of the things you expect them to do might not be as essential as you think

You are operating under a different paradigm now. Without knowing more details it's hard to judge how much your reaction is due to a completely different approch and how much is due to actually unsustainable practices.

  • Specifications - Shared understanding is more important than extensive specifications. I've run into this problem at my last project. Very detailed specifications that were diligently refined from user requirements down to design specs. But eventually, late in the project we realized that the PO understood A, the PM understood B and the Dev implemented C. If your team manages to avoid this then the level of specification your team creates with their user stories is probably sufficient. Clear, testable acceptance criteria for a story can be beneficial but the ultimate judge of your program will be the customer. Nothing tops that.
  • design - Upfront design often fails to honor YAGNI and plans for features that might never come (especially in an agile environment). But again your post is unclear whether they have no concern for design and structure or whether they are just creating it as it becomes necessary. Are designs ever talked about? Are people refactoring design when new features are implemented?
  • documentation - Source code should not have to rely on external documentation to be understandable. Does your team have code complexity in mind? Are variables and function names expressive? Do you have automated tests? If you do then they probably aren't reckless in their approach.
  • database design - If your database can be generated from your code then your code arguably IS the database design. The database in this scenario is likely no more than a dumb persistence layer. If you had decided to serialize all data to xml files instead using your framework's default mechanisms you probably wouldn't expect a detailed file format documentation.

More attention to maintainability might be good for them

Your concerns are healthy and valuable. If you are uncertain about the long term maintainability of your source code then you should investigate. Since you're coming from a very different mindset you should first learn the mindset that exist in your current team. Ask your coworkers how they are adressing maintainability and tech debt. But approach this conversation from a position of "I want to learn how your way works" and not "you are doing it different/wrong".

Then, if - after understanding their approach - you are still not convinced their way is safe, then suggest improvements (the retrospective would be a good place)


Lots to parse here. TLDR; Focus on what's important (maintainable code), rather than jumping to an assumed/unverified root cause (lack of documentation).


First, and perhaps most important, is your perspective. From the tone of your Question, it appears to me as if you're not only unfamiliar with Scrum, but disparaging of it. If you come at a Scrum project with the mentality of "How can I work around this nasty Scrum thing?", then you will fail. Do not be overly concerned with what Scrum doesn't do, and instead focus on learning how Scrum is supposed to work.


From the Agile Manifesto:

Working software over comprehensive documentation

This means, essentially, two things. First, that documentation is important (more on that below). Second, that working software is more important.

You point out the lack of a Software Requirement Specification or Detailed Design. To me, this lack is a good thing. Expending too much effort into upfront design has two side-effects. Firstly, it puts more time and effort into design and documentation instead of writing code. Secondly, it locks the Team into a particular mindset, which in nearly all cases will either be wrong, will become wrong as requirements change, or both - thereby making the Team less able to respond to change and update their code. They will always, in the back of their minds, be trying to 'stick to the plan'. Both of these will harm the Team's ability to create working software - which, again, as per the Agile Manifesto, is more important than documentation.


Regarding the code-first approach (versus a database-first approach, or an approach where both are designed separately and then connected somehow), that is a completely separate Question that is out of scope of PMSE. Suffice it to say, there are, at the least, many people who consider it to be a valid approach.

User Stories

You mention

They only create some user stories

which seems to me as if either you don't understand the purpose of User Stories, or else your Team is not using them correctly. User Stories are a form of (living) documentation. Years later, when trying to figure out why a piece of code was written, you should be able to go from the code to its corresponding User Story, and see it there. If you cannot, then that is an issue that needs to be addressed.

One approach that I've seen work well is to:

  1. Save all User Stories, each with a unique key for easy future lookup.
  2. Include that unique key on the commit message of any code relating to that User Story.

How to maintain the code later?

The best way to be able to maintain code in the future is to write maintainable code. That seems like a tautology, but there are other approaches (such as comprehensive documentation) that some (in my opinion, erroneously) consider to be most important.

There are various ways to accomplish this - code review, pair programming, better hiring, training and culture to obtain/raise/retain better programmers, technological assistance (such as a StyleCop of some kind).


In the end, make sure you're focusing on the right problems. Rather than focusing on Scrum's lack of documentation, instead focus on the goals of Scrum and Agile. These include improving quality of individuals and their interactions, writing working software, improving customer collaboration, responding to change, as well as the various goals of Scrum - see the Scrum Guide. If these goals are not being met, focus on that, including first trying to find the cause, rather than automatically assuming you know the cause (e.g. lack of documentation). If you have a goal that does not line up with the goals of Agile and Scrum, first ask yourself the the project really needs it. In some cases, it does (and therefore Agile/Scrum are unsuitable for that project). In many cases, it does not.


Leaving supportable code is just as important for an Agile team as for a traditional development team.

It is simpler to describe what an Agile team would try to avoid:

  • Don't write documentation just because it is the 'done' thing - i.e. only write documentation that you know will be valuable to people supporting the code in the future.
  • Avoid documentation that is difficult to maintain or that may quickly become out of date.
  • Keep the code (and database) design as simple and readable as possible.

You may also want to consider using self-documenting techniques, such as Behaviour Driven Development (BDD). This is a great way to embed the requirements design into the code base.

Another important approach is to maintain a high level of automated regression test coverage. This is important as it will give developers working on the code in the future the confidence to make changes, while knowing they haven't broken any existing functionality.

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.