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 '_Instructions.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.
- Project structure
All parts that composes the project and how they work with each other.
- Third party components
Any software, tools and DLL files that this project uses. (e.g., NHibernate, ComponentArt, KendoUI)
- Database configuration
- Other configuration information
- Deployment information and procedures
- 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
Recommendation: All manual workstation setup steps should be scripted with powerShell (as per the below example)
Recommendation: You should be able to get latest and compile within 1 minute. Also, a developer machine should not HAVE to be on the domain (to support external consultants)
PS C:\Code\Northwind> .\Setup-Environment.ps1
Problem: Azure environment variable run state directory is not configured (_CSRUN_STATE_DIRECTORY).
Problem: Azure Storage Service is not running. Launch the development fabric by starting the solution.
WARNING: Abandoning remainder of script due to critical failures.
To try and automatically resolve the problems found, re-run the script with a -Fix flag.
Figure: Good example - you see the problems in the devs environment
PS C:\Code\Northwind> .\Setup-Environment.ps1 -fix
Problem: Azure environment variable run state directory is not configured (_CSRUN_STATE_DIRECTORY).
Fixed: _CSRUN_STATE_DIRECTORY user variable set
Problem: Azure Storage Service is not running. Launch the development fabric by starting the solution.
WARNING: No automated fix availab le for 'Azure Storage Service is running'
WARNING: Abandoning remainder of script due to critical failures.
Figure: Good example - when running with -fix this script tries to automatically fix the problem
PS C:\Code\Northwind> .\Setup-Environment.ps1 -fix
Problem: Azure Storage Service is not running. Launch the development fabric by starting the solution.
WARNING: No automated fix available for 'Azure Storage Service is running'
WARNING: Abandoning remainder of script due to critical failures.
Figure: Good example - Note that on the 2nd run, issues resolved by the 1st run are not re-reported
Further Reading
To see other documentation Rules, have a look at
Do you review the documentation?