Incase you are in a hurry, and dont want to refer the entire post, here’s a quick link to a sample README.md file created following the below guide :
I would still advise to go through the post first.
What is this post about ?
This post is all about documenting a web project, by document i mean the series of steps required to get a web project running from its source code available in its Git repository to a latest run-able version of the project.
This post will basically serve as a guide to suggest the various information that is needed to be included in the project document for a web project.
Every project document will have a number of steps which can be broadly categorised in two parts :
- General information required for documenting any software project.
- Project specific steps, information relevant to the specific project.
Why should we document a project ?
During the lifetime of a software project, the team working on it will change on various occasions due to various reasons, therefore the project specific knowledge gained overtime by the developers entering the team throughout its lifetime will be lost, when the developers are switched.
When a new developer is added to the project, he is left with a codebase with no proper set of instruction on how to run it.
Therefore he is now forced to get in contact with the earlier developers.
in case if no one is working on the project at that time this may not be possible if the existing team has left the organisation,
Or get a detailed session from an existing developer regarding the project setup / build generation aspects etc from any existing team member, there by consuming their time.
Also in case if you are a developer at the other end of the story, ie. a developer who has to handover the project to a junior or you are planning to leave the organisation, documenting the project will make life easier for you. When a new developer joins the project all that has to be done is give him access to the source code, and ask him to refer the documentation.
Even after doing the above, if he/she still has doubts only then the intervention of an existing team member is required.
Where should the document be placed ?
The document should be placed together with the project codebase.
In case the project is maintained in git the project document can be maintained as a README.md file in the root branch of the project’s git repository, so that any developer added to the project will first check the document before cloning its source.
In case if it is maintained in SVN or any other file based versioning system, the documentation file should be kept in the root folder of the project with a relevant name containing keywords such as : instructions, README, SETUP etc.
Is this a one time process ?
NO, the steps required to maintain / run a project from its source or to build an executable / production output file will update over time during the project’s lifetime, therefore the documentation which reflects the same also need to be upgraded when this happens.
How do i validate the documentation i created for my project ?
A project documentation is like a recipe to prepare a food dish, you start with the raw materials :
- The source code of the project in case of a software project
- The raw materials, such as spices, condiments, grains and meat in case of a food dish
We then follow the recipe till we get the output:
- A running project in case of a software project.
- A delicious serving in case of a food dish.
Validating a project document is therefore same as validating a food recipe, follow it as if you are the person it is written for. if you can follow it till the end and get the desired results, without getting stuck, the document is valid.
what are the rules / language / syntax to write a project document ?
There are various frameworks and tools designed specifically for the purpose of documenting a software project, but these are usually bulky and have a learning curve of their own.
I believe that documentation should be like a good story: simple, beautiful and easy to absorb.
Therefore for small to medium sized projects we can document it as simple text instructions and code snippets / commands itself spanning from a single file to a few separate files to the maximum.
For projects hosted on git, almost all git servers support Markdown, a lightweight markup language with plain text formatting syntax.
This is a very convenient way of documenting notes, code snippets commands, screenshots, links etc all of which will usually be part of your documentation.
Please refer this for a detailed guide about markdown.
Also you can use this WYSIWYG markdown editor for writing documentation easily.
Without further ado let’s dive into the actual contents of a project document.
- Begin your documentation with a welcome note.
Welcome to XYZProjectthis would better be in the biggest heading.
2) App or Organisation logo
3) Give an overview about your project
This section should contain a one to two line non technical overview of your project
A SOME_ABC Company Pvt Ltd employee management app4) App and team information
App Name : ABC Rocket
Customer : SOME_ABC Company Pvt Ltd
Development Team :
John Dev (Android developer : May 2018 - June 2019),
Jane Dev (Android developer : June 2019 - till date),
Jonah Dev (Backend developer : May 2016 - till date)
Design Team : Wan Chung, Lee Chi
Management : Nikola Tisola (Sr Manger : May 2012 - June 2016), Thomas Eden (Sr Manger : July2016 - till date)
Web URL : http://ROCKETAPP.SOMECOMPANY.COM5) About document File
This section gives the importance of maintaining the current documentation file and general instructions related to the documentation file.
About this file
The purpose of this file is to provide overview, setup instructions and background information of the project. If you have joined this project as a part of the development team, please ensure this file is up to date.
Note : Any dependencies added / modified to this project which affect the running of the code in this git repository must be listed in this file. All developers must ensure that the instructions mentioned in this file are sufficient to enable a new developer to obtain a executable copy of the lastest code in this repository, without invlvement from any other human assistance.6) Tools and Hardware Requirements Declaration
This section is basically a checklist of the minimum hardware and software tools etc which are required for running the project
I) Software requirements
1) Ubuntu OS
2) Maven
3) JDK
4) Camera drivers
5) Web Cam Device
6) Http Server
7) MySQL and MySQL drivers
II) Hardware requirements
1) Minimum 8 GB RAM
2) Minimum 12 GB Available Disk Space
3) Wifi Availablility
4) Web Camera7) Project Technical Specifications
This section is basically a high level overview of the technologies used in the project and steps involved in generating the final builds for the project
* This project is a cordova based project which uses Angular 7
framework.
* The angular code is first compiled using angular-cli commands,
then the output is moved to the cordova www directory. After which
the cordova build command generates final android / iOS output. * The API is provided from customer
* The design for reference is from XYZ Company Pvt Ltd Mumbai design
Team.8) Setup Instructions
This covers the actual setup of the project from fetching the source code, installing the dependencies, setting up environments, build generation etc.
This section can become huge and can be saved in a separate SETUP.md file if necessary. The link for which must be given in the main README.md file.
ALL OF THE SUB SECTIONS MENTIONED BELOW MIGHT NOT APPLY TO YOUR PROJECT INCLUDE THEM AS PER YOUR DISCRETION.
Setup Instructions
As mentioned earlier , this is a cordova-angular project,
The below mentioned steps may vary significantly across various operating systems, please follow them accordingly.These instructions are aimed at a developer who has been added to the project team, after the project development has already been initiated,Therefore the aim is to get the code from the git repository to run on the developer's system, so as to allow him / her to continue with further development.
8.1) Fetching git code to local system
This section must include the commands required to fetch the source code from the git repository, Once this is done, then the commands required to checkout the proper branch on which the developer needs to continue working.
Clone the repository from GitLab :
git clone git@gitserver.abccompanygit.com:root/rocket.gitChange current working directory to Project directory
cd Rocket( This is the cordova as well as the angular root folder. )Checking out the latest development branchAs of writing this guide the main branch used for development is : develop
To switch to this branch : git checkout develop
8.2) Installing project specific dependency packages and tools
INCASE ANY SPECIFIC VERSIONS OF A TOOL / DEPENDENCY ARE REQUIRED AND THE PROJECT DOES NOT BUILD / WORK PROPERLY WITH LATEST VERSIONS OF A DEPENDENCY, MENTION THESE INLINE ALONG WITH THE COMMANDS TO INSTALL THE DEPENDENCIES
Installing dependencies
This project requires cordova for running,You can install it by referring to the official cordova page : [https://cordova.apache.org/]The cordova version used at the time of writing this file is : 8.1.2You can check the installed version using cordova -vThe config.xml file contains the list of all cordova plugins and platforms used for this project.Please ensure this file is updated incase any plugin is added / removed.Please follow below steps for installation :Install Angular and Cordova NPM Dependenciesnpm iNext install cordova platforms and pluginscordova prepareIncase you get errors as : Current working directory is not a Cordova-based project.The www folder used by cordova cli to detect a cordova project might be missingSimply make an empty www folder via file manager or via commandline as :mkdir wwwInstall cordova android platform
cordova platform add android
8.3) Commands / Instructions for starting a server / OS service required by the project to run etc
Start the http and mysql xampp server :
xampp http start
xampp mysql start
Start kurento media server
sudo service kurento-media-server-6.0 start
9) Build generation commands / Instructions
These commands and instructions will utilize the tools and dependencies installed above and generate the output files from the source code, such as an .apk or .ipa file or a dist folder containing minified web code ready for deployment.
10) Build environment information and switching information
This section contains a detailed list of information or a reference to the same, giving details about various development environments such as UAT, DEVELOPMENT, PRODUCTION etc.
These should also have instructions for switching between the various environments.
Eg. Once a developer generates a build for UAT environment and is tested and approved by QA team for deploying to production, this section must provide steps for switching the API endpoints to Production URLS, KEYS to be used in production etc
11) White labelling instructions
In case the project you are working on is a white label project, ie. The same software product is used for multiple customers, then the documentation must include details pointing out the code level differences between two instances of the same project, features enabled / disabled for specific instances, instance specific details. Steps to create a new instance from existing instances etc.
12) Deployment steps
Details related to the platform on which the final software product is deployed, eg. Android Play Store or Apple App Store or a web server.
Such as references to login credentials, file server paths etc.
NEVER STORE LOGIN CREDENTIALS OR OTHER SENSITIVE INFORMATION IN GIT README FILES,
README FILES ARE ACCESSIBLE TO ALL USERS WHO HAVE BEEN GIVEN ACCESS TO THE GIT REPOSITORY.
HOWEVER NOT ALL USERS ARE AUTHORISED TO UTILISE THEM. THIS MIGHT LEAD TO PURPOSEFUL OR UN PURPOSEFUL DATA / PROPERTY LOSS ON PRODUCTION ENVIRONMENTS.
MENTION ONLY THE DETAILS OF PERSONNEL / DEPARTMENT WHO HAVE AUTHORITY TO PROVIDE SUCH CREDENTIALS IN THE README ONLY
13) Unit Testing or Basic testing steps
Once the developer has finished setup, he would want to verify the setup process, by running the application in local or test mode.
The documentation should therefore contain links to the outputs such as file system paths of the generated build or web url for a web app.
14) Notes for future maintainers
This section must contain instructions aimed at developers from future point of view, such as advice on writing future code, installing new dependencies etc.
15) References
This section contains mostly links to non source code resources such as Application Design References, Wireframes, Requirement Documents, Existing Apllications, Demos, etc
For a sample README.md file created using the above guide refer :
https://github.com/T1TAN1UM/WEB_README_SAMPLE/blob/master/README.md
