In the prior rule:  Do you review the documentation? we learnt of the 6 documents

​There are 4 levels of project documentation. Documentation can start simple but ends up having a lot of manual steps. The best projects have simple documentation but more done automatically (level 4).​​​

Level 1 - Lots of documentation step by step​​​​​

Add a document as a solution item and name it '_Instru​​ctions.docx' 

​​Tip: Microsoft Word documents are preferred over .txt files because images and formatting are important

You can also break up this document into 4 smaller documents

• _Business.docx - Explaining the business purpose of the app
• _Instructions_Compile.docx - Contains instructions on how to get the project to compile
  
• _Instructions_Deployment.docx - Describes the deployment process
• _Technologies.docx - Explaining the technical overview e.g. Broad architecture decisions, 3rd party utilities, patterns followed etc

Here's a suggestion of what these documents could contain. 

1. Project structure

   All parts that composes the project and how they work with each other.

2. Third party components

   Any software, tools and DLL files that this project uses. (e.g., NHibernate, ComponentArt, KendoUI)
   

3. Database configuration
4. Other configuration information
5. Deployment information and procedures
   
6. Other things to take care of

Bad example - A project without an instruction.

Good example - A project with instructions​

Add a readme.md to your solution (Use this​  as a guidance for markdown)​​

​​​Level #2: Lots of documentation (and the *exact* steps to Get Latest and compile)

When a new developer starts on a project you want them to get up and running as soon as possible.

If you were at Level 2 you might have a document that says:
Dear Northwind Developer
     This documentation describes what is required to configure a developer PC.​

Problems to check for:
​​Windows 8 not supported
​​Many things to build
​​​Lots of dependencies​​

You are at Level 2 when you have some static Word documents with the steps​ to compile. The _instructions_compile.docx contains the steps required to be able to get latest and compile.

Level #3: Lots of documentation (and the exact steps to Get Latest and compile with the *database*)

Figure: Level 2 Documentation includes database build scripts. We use SSW SQL Deploy to make keeping all databases on the same version simple. Check out how to use SQL Deploy here

Level #4: Less documentation (and Get Latest and compile with a PowerShell script)​

A perfect solution would need no static documentation. Perfect code would be so self-explanatory that it did not need comments. The same rule applies with instructions on how to get the solution compiling: the best answer would be for the solution to contain scripts that automate the setup.

Example of Level 6: PowerShell Documentation

Further Reading

To see other documentation Rules, have a look at Do you review the documentation?