Sharing knowledge in a company - options?

[Nerseus]

First, congratulations to me - my company has been bought by 3M!

As we moved from a small company to a large company (from 8 to about 80) we experienced a number of issues - which we've overcome (not without a lot of work and growing pains).

Now we're expected to double in size in the next year (up to about 150 people). Besides the issues of just finding the right people, we're finding ourselves with new kinds of problems, such as keeping our codebase consistently high quality.

The main question is (I hope):
How do you share knowledge among many developers? Our company has a product that is sold from state to state (and soon to be international). Each area is overseen by one architect. Each implementation (each state) has a technical lead that knows that one area pretty well and can assign work and think of issues as new features are added.

The goal is to get that knowledge that is currently only known to 1 or 2 people into the hands of many. For example, if I leave the project we need others to be able to come in and take over. Also, if I leave the project for a year and come back, how am I to remind myself of all the "gotchas" that are currently just in my head?

I can think of 3 main options, but maybe there are more:
1. Paper documentation. This would involve writing "Tech specs" (as we've internally called them) that document the code at a medium level (down to class and method names, stored procedure names, etc.). These are organized around some subject area (generally some UI). They are meant to be kept up to date with code changes.

2. Test Driven Development (TDD). This would mean the code documents itself through unit tests. To understand how a system works, you look at the tests. I've never done this before, but seems like it may only be 1 piece of a puzzle.

3. Funnelling knowledge and review. This is what we have now - a few high level people know all about the system. They hand off work and then review the code to make sure there are no bugs (those that a non-informed dev wouldn't know about).

-nerseus

 

[irasmith]

First off, congrads on the good fortune of being in a growth mode, my hat off to you on that one

You do ask a good question and you do have some good thoughts. After reading your post and giving some thought to it, here are my comments.

As far as TDD, as I understand it, the primary focus is to provide a way to constantly test the system under development so that you know when something is broken. True, in working with it throughout all of the building revisions you do get an idea of how something works by virute of trying to figure out why your code changes broke it. I have never attempted it but I guess if you read through and studied the tests themselves then you would learn a lot about how the program was supposed to work.

That all being said, I am not an all traditional or all full blown agile guy. I see benefits of both methods and in a way can see many benefits of combining techniques from both.

I like use cases very much. If they are done correctly, they can be lightweight documents that will become the hub of your knowledge base. Personally, I like the natural style of reading that they lend themselves to. If you don't go overboard in detail in them then they will allow you to get a very good general idea of what the system should do.

From there you can branch out into a combination of other forms of documentation focused on a specific area such as UI as well as using some TDD tools as well.

I believe in adapting to the situation and so I never feel one way will fit every situation.

I recently had great success on a project where I needed to get several people up to speed quickly on a product. I was very familiar with the product and so I wrote a lot of test cases. I designed each test case to be a lesson in a specific aspect of the product, keeping in mind to focus in on the most common aspects that would come up not the extreme rare exceptions. I designed the test data that each case used to help prove the point trying to be conveyed. By the time the folks who needed to learn the system worked their way through the test cases, they had a really good level of confidence in themselves that they knew a lot about the system and were not frightened off by it.

Sure, there were still things that had to be learned, but the bulk of knowledge was transferred by walking through the test cases step by step paying attention to what I had outlined as the expected outcome for each step and comparing that to their actual results. Hence the goal was not to run through the cases as quickly as possible like an automated test. This was a process of reading the goal of each case, the overall expected result that would be the intended outcome, and then walking through it step by step to achieve that goal.

 

[tfowler]

How do you share knowledge among many developers?

In our company, we create a "Project Binder" for each project. The Project Manager owns the binder and is responsible for keeping it up to date. The binder contains:

- Project Definition - basically a summary of customer-specified requirements
- Software Requirements Specification - a detailed listing of requirements created from the customer-specified requirements, company requirements, previous project knowledge, industry regulations, etc.
- List of Project Personnel and their roles - this includes developers, testing personnel, as well as the customer contact information
- Architecture Documentation - can include UML diagrams, class and function descriptions, etc.
- etc.

We then have Design Reviews for each document release, and for any documentation revisions. We also have code reviews at pre-determined intervals.

As you can tell, we are definitely not following the agile model. We use unit testing to ensure the code is working as expected, but we do not tend to use unit tests as a design tool.

Our main products are hardware-based (sensors, instruments, systems, etc.). So, we stole a lot of the design process from the hardware engineers. It can seem like a lot of up front work, but it pays off in increased quality and decreased troubleshooting, re-writing, and code maintenance. It really keeps everyone up to speed on the project and ensures that there are no surprises.

I've had a lot of messy code to maintain over the years, with minimal or no documentation (including minimal code comments). It could take me a month or more to just figure out what the code is supposed to do, let alone fix it. Having the above documentation greatly decreases the time needed to get up to speed and find the problem.

Todd

 

[PlausiblyDamp]

I personally find that

Paper documentation.

can work very well if you remove the paper bit from it Rather than relying on physical documents, which cause problems with multiple revisions being in circulation etc, a more on-line form such as a wiki or a SharePoint system works well.

An Intranet based system means everyone always knows where the current version is, and more importantly if using something like a wiki or sharepoint all previous versions can be maintained and viewed. This makes tracking changes etc. far easier. Couple this with basic security to limit who can make changes as opposed to who can suggest changes and you can end up with a very workable system. If this also includes basic bug / incident tracking then you have a single place for all relevant information that can be linked using the magic of a href - no more manually searching for related documents base on arbitrary document name / numbers.

When it comes to TDD

As far as TDD, as I understand it, the primary focus is to provide a way to constantly test the system under development

Unit tests provide two main functions in software development, firstly they do provide a way to reliably and continuously test software during the development cycle; a side effect of this is the ability to perform code refactoring with an enhanced degree of confidence.

The second thing they provide is a definitive 'specification' for the software by removing any ambiguity. If you cannot read part of a more formal specification and then generate one or more tests that can be used to prove the validity of the code (about to be?) written then the specification either isn't clear enough or has failed to consider all possibilities.

Once written (and like any written code), reviewed, refactored and repeated these become a 'specification' that is much easier to read when in developer mode - you do not have to interpret meaning from wordy documents, you can read code and associated comments to understand the requirements.

Funnelling knowledge and review

Any kind of non-confrontational review is something to be applauded IMHO; in fact as well as a more formal review of junior developers code by senior developers I would encourage a more informal peer review system. If more than one junior developer sees a piece of code then no one developer is essential; if they leave for whatever reason at least one other developer is passingly familiar with their existing code.

Reviewing each others code does provide a valuable glimpse into other parts of the system and fosters a more general understanding of the system as a whole, while also tending to provide a more consistent coding standard without always needing the 'big stick' approach.

Ultimately I think sucessful sharing of knowledge is a combination of multiple actual methods, but more importantly a good mixture of good people. If people are keen and the chosen tools work information will spread.

Idiots, egotists and people unwilling to share or change need to be removed as these are often a cause in information failing to propagate...

And finally congratulations Nerseus - looks like your hard work has paid off