• They are lost at the beginning

• They recognize the area so it…

Consume their time

because they need to became familiar with a product, team, solution, architecture.

so existing developers must describe them all of these details, Does it bad? Not exactly it is a great opportunity to meet each other and begin some interesting discusscusions and ideas

Risk and costs for existing project

, but there is a huge risk that something is missing because some topics could be obvious for devs with longer experience in particular project

How to improve it?

There is an option to create a documentation and tell new devs that they need to read it. Great idea? Partially…

Not every documentation is good. How do I describe a good documentation:

• Up to date - It is the most important. When documentation is outdated there is no sense of reading it. I would be the waste of time
• Real examples - Examples are crucial to simplify understanding what we are talking about.
• Simple - If something is simpler then we are more willing to update it and read it.
• With a context - Sometimes documents were created in the past in specific situation. It is required to know the context. It allows people to understand why it is like is.
• Open for updates - Allow people to update it if it is required. They will feel, they have a real impact and they will care of it.

Ok… but how to make documentation like that? I would not suggest creating a special documentation for new people. I would suggest using…

ADR

It is a natural way to persist and document decision in a project. Then you will have all of advantages from ADRs. I wrote a bit about in an article about Architecture Decision Record .

Moreover, you add it as a step in a project’s introduction. New devs should read it one by one and then:

• They will know what approaches are in the project
• They will know the context of some decisions from the past
• They will be asked to comment any of that decision, maybe they have better solution to described problems
• They will have real examples in the code
• They will know what assumptions are, se they would be able to follow them
• They will know how to introduce new ideas into the project to improve it

Would you like to add anything?

If no - leave here a comment and tell me what do you prefer coffe of tea? If yes - leave a comment or create a PR to that post in GitHub

You should have an updated documentation, with real examples, and with a

• User guide - gread idea The best option is create

Start using ADR

• Other developers time, because they need to describe everything