We recommend:
- Add a document as a solution item and name it '_Instructions.docx'
- Add a readme.md to your solution (Use this as a guidance for markdown)
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. They are not compulsory but may be necessary for running the project.
- 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)
- Database configuration
- Other configuration information
- Deployment information and procedures
- Other things to take care of
-
- Bad example - A project without an instructions.
-
- Good example - A project with instruction
When a new developer starts on a project you want them to get up and running as soon as possible.
Problems to check for:
- Windows 8 not supported
- Many things to build
- Lots of dependencies
It is essential to have documentation that describes what is required to configure a developer workstation.
There are 3 Levels of this documentation in a project.
Level 1: Can you get latest and compile with a Docx
-
- Figure: Level 1 documentation is static word documents. The _instructions_compile.docx contains the steps required to be able to get latest and compile
Level 2: Can you 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 3: Can you 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 3: 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?
