How to build project's knowledge base?

Question

The problem we have now in our team is that sometimes, when you need to start with different module/component you need to spend huge time amount for reviewing and understanding this part.

How it works, what it does, what pitfalls, or some project's size manuals how environment or stubs can be set for component setup or testing, for example.

I find this situation very hard, because when you start to working with someone else code, first you need to ask him for very long time period huge amounts of questions accordingly to "his part", before you can understand it enough and start by yourself.

So, this is some sort of project's documentation. Developer notes, component's/ticket's business process and work-flow.

How developers have to work to eliminate such problems for future maintainers?

Maybe we should post much more information to our tickets' description/comments - so when you need to grasp some new component, all you have to do is to search for all tickets of this component and read them. What do you think about it?

Maybe you can recommend some book on this issue..

How this problem can be solved? Daily meetings, pair programming, solid project's wiki base?

Answer 1

Most importantly always have code reviewed before it is submitted. If the group is ensuring consistency of style within itself, it becomes much easier to read each other's code. If the reviewer cannot understand a section of code then appropriate comments should be added or changes made. Code revision alone can solve many of your problems by ensuring: * Consistent style * Meaningful variable and method names * Code divided into classes that make sense * Comments to explain whatever is not easily understood

Another helpful technique is quick daily "standup" meetings in which each person describes what they did during the previous day and what is planned for the next day. As a result if you have to look at someone else's code (in your group) you have a general picture of what they have been doing and can hit the ground running.

Answer 2

first you need to ask him for very long time period huge amounts of questions accordingly to "his part", before you can understand it enough and start by yourself

I find this is often an indication (but not always the case) the code isn't very well documented. Encourage your co-worker to document what they've told you, or do it yourself if you can't convince them. It won't be of immediate benefit for you, but it will save your or your co-worker's time later down the track when others read the code for the first time.

How developers have to work to eliminate such problems for future maintainers?

Again, if you or others have trouble understanding some code, write some documentation!

Maybe we should post much more information to our tickets' description/comments

I'd recommend against this - tickets are for tracking the resolution of issues. You shouldn't be documenting how your code works in your issue tracking system.

How this problem can be solved? Daily meetings, pair programming, solid project's wiki base?

Yes, you've got the idea! Good code comments, a wiki for higher level documentation, pair programming and daily standup meetings are all tools to help improve your team's knowledge of your code.

Answer 3

Wiki is known as a good practice, however mostly long articles and instructions are taking place in those project wiki's and small life-saving details are lost in space as I observe.

I suggest a micro-blog instead. Which contributors just add their "distilled" knowledge as a record, with strong tag/category. I think its more efficient and more attractive to contribute since developers usually like motto-style sentences ;)

Answer 4

Have the original developer do a code walkthrough as a screencast while everything is still fresh in their mind.

Answer 5

Written documentation has an issue of often being "write-only". Meaning people happily write explanations and articles but when a question arises everyone just prefers to ask someone than trying to look for an answer in the knowledge repository.

Look at SO or any other community site for that matter. People have a question and they just ask it, without searching for similar question here and even without googling for an answer.

Active in-team communication should be the most helpful. A good practice would be to somehow mention the authorship in modules/source files so that it is clear who could be a consultant when there is need in explanations.