How to write technical documentation of a web site/software for new developers?

Question

I want to make a technical documentation of an existing web site for developers so that new developers can continue to work with it. In existing codes, little (or not at all) in-code comments or doc-strings are available (bad practice, I know). Yeah, I have seen some posts related to these. But those were not that detailed. Here are all my questions:

• What to include?
• How to organize? I mean, can you suggest some hierarchy so that new developers can easily get onto the track?
• What are the best practices?
• Can you show some samples?
• How can it be made easy? Some ppl suggests wiki tool but I know nothing about it, will it be useful? Can you suggest any tool with some quick starting tutorial?

I have never made one. So I appreciate any kind of answer. Thanks in advance. (Links will be helpful but please give a quick and lucid summary of it)

Answer 1

Quick and lucid:

---

Think of it like any paper.

What is the goal of the app (website)? [why?]
How does it achieve this goal?
What problems have arisen?
What problems could arise?
What could be expanded upon? [why?]
What problems could expansion cause? [why?]
What naming/formatting conventions should continue to be followed?

• Outline format is great.

Answer 2

In addition to Nona's suggestion I would also say that it is important to break down the code and explain any conventions and intentions of the code so that there is uniformity between developers for things like ID values, CSS classes, and JavaScript function names. Be as specific as you determine necessary to prevent a new person to the team from reinventing work.

Answer 3

If you're looking for a quick way to get through your code, try .NET Reflector. It gives you a broad overview of all your classes, methods, properties, etc. so that you can write all the technical documentation you need without actually going through the files. It's super easy to browse through and it will even show you the code itself.

Answer 4

Have you thought about representing what is there with some UML notation? That's what UML is for! If the new developers are good then they should be able to understand it.