I know it is obvious but i guess people still ignore the fact that documentation and knowledge sharing is important. Through my career as developer (so far 8 years) i have not joined a single project nor company that would have a proper up to date documentation. As a result it takes half year to catch up, instead of 3 months, for every new person joining the team and it causes constant headaches. I believe that could be improved if there was proper high / mid level documentation.

I know, I know, all the 'lazy developers' will jump and scream "but you should not waste time on documentation! code should document itself!". Well great, should IP addresses, web services, database schemas also document themselves? Being lazy is not a virtue, even that it seems to be cool.

Document projects on the wiki

I believe that every application and system should have a wiki starting point which is an overview for new folks. Describing overall high level architecture, integration points, dependencies etc. Then going deeper every bigger story (scrum story) should come with a basic wiki documentation describing what were the initial requirements (attachments are ok) and simple implementation description. It is also handy to note all testing tips and pitfalls as it is very common that components have their funky parts and developer who have never seen them will waste time trying to figure them out.

I think it is really not such a big deal to write one screen of notes. Developer adds a diagram from time to time, one screen of description, pastes some emails describing agreed requirements. Is that so hard? Then once you have a lot you restructure the content a bit. It really can be done. Even that very few people write any documentation i have been doing it for last three years and it really does not take that much time. In return i always have point of reference why did i do it and how etc. I do not have to repeat myself describing how to use it or how to test / retest it. It really works.

Which wiki should i use?

Confluence from Atlassian is great! It is the best wiki i have worked with. You have tree structure and free linking available. You also have comments, versioning, history, diff and snadboxes for people to work on drafts. Search works very well. You can easily attach and see attached documents and wiki syntax is easy to use. It even looks nice.

Second best i have used so far would be media wiki but it is far from perfect. Search is poor, there is no tree structure so all the pages are randomly linked from one to another. It makes life much harder when you want to find something and you are not sure where was it. Its also much harder to use for new members of the team. Syntax is not bad and i guess it is usable. Attachments are not showing as part of the page for some reason and in general are poor. There is no preview of docs inline etc.

Moin Moin and TikiWiki as well as Trac are really bad. I would not recommend them. Syntax is bad, search is bad, they look horribly and have tons of usability issues. At least i did not enjoy any one of them.

Document the architecture

You should have a few pages of overall high level architecture so that anyone could refer to it. Diagrams and some descriptions. It is also a very good idea to describe inter dependencies between subsystems. You should have full live/qa/dev servers structure map so you would know what are the host names, what ip addresses they have, what applications are served from them etc. Without network and system dashboard people will not be able to fix live issues or deploy software correctly.

Document your code

Well again this is really obvious but code should never pass review or go to production if its not tested and documented. I think every serious dev shop should have basic code review process with strict rules - no comment = no build.

There is nothing more to say here, code has to have comments. Statement that code documents itself is a hacko-wacko-perl-ruby advocacy and i think there is not place for it in large scale applications with dozens of people coming and going.

Do not use Word

I think some of you wont believe but word is still holding on in agile houses! I do not know how come as it is the most destructive collaboration tool ever :) Even in current project i have to deal with doc's from time to time. It is not fun and it can not be parallelized nor versioned. The best we can do is to have a file names with version numbers.

I guess for client facing specs that would be ok but for internal documents its a mistake. Do not use word, use wiki or document in your code.

Word doc is not better than no doc. You cant search it, it is local, it does not support metadata nor versioning nor audit trail, nor is it accessible at all times to all the team members. Just do not use it.

Summary

My appeal would be, be a responsible team member. You are not the only person working on the system. Please consider what information would be necessary to do fix a live emergency issue, what is necessary to know to release a new version of all the packages. Ask yourself what would a person have to know to develop a new application or component using our in house system. Or maybe how do people roll out database migrations, backup, schema changes.

I believe every of these questions should have some sort of information wiki page.