Two months ago I joined a development team for implementing new features over a software that evolved over 10 years. The current state is that there is very few documentation and in order to develop a new feature, there is only the architect who completely understand everything, so the developers need to implement what he designs. The problem is that the system has so many components, that as there is no documentation the developers need to ask many questions to the software architect. Macking him a big bottleneck, as we have 10 developers.

The question is how to improve this process? What would be the right documentation for this case? I am afraid to ask the developers to write very detailed documents about what they are learning while struggling implementing. I think UML diagrams would be too detailed as well. Could you please suggest me any good representation models that would give a quick big picture of the components involved in a new feature?


  • Possible duplicate of What kind of process should I use to learn a big system?
    – gnat
    Commented Nov 10, 2017 at 12:04
  • 1
    You are wrong sir. That question is from the new developer point of view. I am asking from the project manager point of view. How to make things better, how to "save" this project and to improve the development process.
    – adam13
    Commented Nov 10, 2017 at 12:16
  • 1
    The right kind of documentation depends on the software (maybe different docs for different components of the product) and the team. So, as a project manager, you should ask the team what kind of documentation they need for their tasks. Note also, learning a new system takes time, there is no shortcut around this, with or without any documentation.
    – Doc Brown
    Commented Nov 10, 2017 at 12:25
  • 1
    How much room is there to train other people up to the level where they can be experts on a specific part of the code?
    – Onno
    Commented Nov 10, 2017 at 13:54
  • 2
    As I see it, you need to change priorities. The developers asking the architect is not the problem, it's the solution. Focus on him delegating information to others rather than trying to bug him as little as possible so that he can do it. That's exactly the kind of reasoning that got your in this position in the first place.
    – Neil
    Commented Nov 10, 2017 at 15:00

3 Answers 3


The architect needs to stop designing the system for everybody else

For now, the architect is the only person who really understands what's going on; by allowing the architect to continue to provide designs to everybody else, this problem can only get worse. Documentation isn't going to change this - the architect will always be a bottleneck as long as they are the only one involved in the design process.

Suggest to the architect that s/he should slip back to an advisory role whereby they are no longer responsible for taking these decisions, but instead spending their time mentoring the team, answering questions, reviewing requirements, providing feedback on design proposals and making time to talk other members of the team through the codebase.

Focus on the problem of knowledge sharing, not on documentation

The team may decide that some documentation is useful for their future reference, however this should be motivated by their needs in understanding the system. Keep an open mind about the format of any technical documentation - the team may find find that it's more beneficial to maintain some kind of Wiki or Notes repository where anybody can add useful snippets of information, rather than trying to work around formal design documents.

Avoid taking a simplistic approach of assigning documentation tasks; you're more likely to end up with a large quantity of rather useless documents that nobody will ever read, until somebody digs it up one day and finds that it's heavily outdated, filled with obsolete information, and ends up being deleted.

Instead, put an emphasis on collaboration across the whole team (including the architect) for any matters involving design and architecture - no single person should be responsible for unilaterally taking such decisions, as this is how "silos" of knowledge are created in the first place. Documentation can be a by-product of this approach, wherever it feels appropriate; for example, the team may spend time in a meeting room with a Whiteboard, and may decide that the information on the whiteboard deserves being transcribed into a document (or maybe just a photo of the whiteboard will be enough.)

Open up the system design process to the whole team

Ideally, everybody in the team should be able to have the opportunity to be involved in any discussions or decisions about design/architecture. Not everybody needs to be an expert at everything, but it works best when everybody stays in-the-loop and is encouraged to get involved or provide feedback when new requirements emerge.

When new work is assigned, choose another member of the team to be propose a design, and ask other members of the team to be involved in the review and feedback process. The more people in the team who are actively responsible for continued growth/evolution of the system, the easier it will be for everybody to work on the project.

Reset the architect's role in the team

While the architect will always have the loudest voice, their position should be about enabling the team to make the right decisions, rather than making a decision for the team. For example, the architect may step in when the team can't agree on something. The architect also needs to guard against flawed designs which might risk the stability of the system (the architect is still ultimately responsible for the integrity of the design, so they always have the power to say "no", although it's important that the team understand the reason why something is bad/wrong).

By opening up the design process to the whole team, there are more opportunities for knowledge and ideas about the design and architecture of the system to spread and 'cross-pollinate' to the rest of the team. Over time there should be fewer issues; spreading knowledge means the team and the architect should start to align, and are more likely to converge on these decisions.

This will naturally lead to everybody in the team asking a lot more questions to the architect at first; the architect will always remain a key player in the whole process, but in time the number of questions will decrease and they will cease to be a bottleneck

Some documentation is nearly always valuable

Documents filled with class diagrams, flow diagrams and other such banalities are unlikely to do anything other than burn a whole load of time for something that nobody will ever read, but projects often rely heavily on other kinds of documentation which sit at a higher level than the codebase.

For example:

  • Requirements and user/stakeholder expectations - Everybody involved in a project needs to be in mutual agreement about this; it's hugely important for requirements to be captured and agreed somewhere, otherwise you can easily end up with misunderstandings between the team and the end user or stakeholders.
  • Acceptance Criteria - developers need to fully understand the bar against which their solutions will be measured. Acceptance criteria should be agreed with stakeholders, so it needs to be documented so that developers have something unambiguous to refer to when testing their solution
  • System architecture - it's often useful to have a high-level view which shows relationships between the top-level system components such as databases, web services, 3rd-party APIs, hardware modules, etc. It's also useful to describe the interfaces between those components, as well as describing the function of the main system modules.
  • Functional Specification - This should describe of the main features of the system, and enough detail that somebody unfamiliar with the system can understand what those features are for and how to use them. Also consider information such as how to deploy and configure the system, how to start troubleshooting user problems, where to find diagnostic logs, how to backup the system, etc.
  • Thanks a lot! Your response is exactly what I was looking for, it gave me many ideas to work in. I omitted some information such as that the team is in America, Europe and Asia. So the problem gets even worse because the architect is in USA. So the communication is unluckily not the best. But still, the answer gave us many ideas to work in.
    – adam13
    Commented Nov 13, 2017 at 11:33

Everybody start documenting!

If you're "doing " Agile, then add "Documentation" to your Definition of Done. Exactly what that documentation comprises will evolve [rapidly] over time but if the Item's not even on the List then it's never going to get done.

You have the luxury of having one person who actually understands the whole thing. Do they look both ways before crossing the street? Seriously, this person could "disappear" tomorrow and all of that knowledge would be lost.

You're in a bad place right now but it's only going to get better if you all agree to make it so.

I am afraid to ask the developers to write very detailed documents about what they are learning while struggling implementing.

You're struggling to implement anything because you don't know what you're working with, but the only way to know what you're working with is to document it.
I would suggest approaching building documentation as a Process, just like building software. Get Developers to start the process off, writing down what they think /have worked out each component does, then pass that to the Architect and get them to correct/ amend/ extend the definition.

  • Thanks! your response has confirmed me that we need to write documentation since yesterday. But my question goes to the direction of what kind of documentation to write and how to do it in a manner that will be really used and easy to understand. The project has many modules, and the new features we are working with require a good understanding of many modules. If we document everything of every module, it may take too much time to read, and to get a good understanding of what is going on.
    – adam13
    Commented Nov 10, 2017 at 12:44
  • 2
    @Adam13: Documentation is all about its target audience - in this case you and your team. Don't "buy into" any particular documentation style/ tool/ methodology and spends days/ weeks/ months trying to get to grips with it. Use what works for you. Exactly as you would with software, start with the Mininum Viable Product - a catalog (a.k.a. "list") of every component and an "outline" of what each one does. Then get the Architect to start filling in any blanks.
    – Phill W.
    Commented Nov 10, 2017 at 14:39
  • @adam13 Developers will naturally become specialized in specific modules as they learn more about the program (developer working on a particular module will know the most about how it from having repeatedly asked your guru). Have each one write his or her own documentation on that module, ideally with the possibility to link to other shared developer documentation. Lastly, having an "open editing" policy (MediaWiki comes to mind) would likely be most prolific in terms of generating documentation.
    – Neil
    Commented Nov 10, 2017 at 14:54
  • Also, focus on what you need to know now (i.e., document as needed). Don't waste your time figuring out details that you might never need to know. But, be sure to write down whatever you learn while trying to solve an actual business problem. Commented Nov 10, 2017 at 17:30
  • 1
    @adam13: didn't I already write "ask the team"? If two different people tell you the same, you should consider to listen to them.
    – Doc Brown
    Commented Nov 11, 2017 at 8:36

In this particular case, I would suggest that you look at tools that can generate a “big picture” view of the system. So, you could task a member of the team (but not the architect) with generating class diagrams and call-graph diagrams on a per module level and per use case level for each respectively.

Then print the diagrams out large enough to be pasted on a wall and seen with the naked eye. Get the developers and the architect over to the wall(s) and ask questions about everything.

The kind of information that you want the architect to share is a big-picture view of the system, why it was architected the way it was and what each piece is trying to accomplish.

This type of visualization can also help identify problem spots.

Other answers to this question are good for long-term planning on how to avoid this silo from continuing in the future, but “reverse engineering a whiteboard of the high level view” can help get things unstuck in the immediate term.

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.