At Mobnia we pride ourselves in building digital products that help you succeed. But how do you build a software product that is reliable and robust? This is the second in a series of posts that address this question.
Before you get started on a software project, there are preparations you need to make. There are tools that you'll utilize from the beginning to the end of the project to help keep team members focused and the project on track.
Your project will have lots of documentation (requirements documentation, use cases, test material, test plans, etc). On top of that, many of the documents evolve over time (requirements may change over the course of the project). It's important to be able to check the documentation and see what you're supposed to be doing. You need to have the most up-to-date version of whatever you need. You'll also want to have older versions of the documentation, to find out what changes were made and their context.
In addition, race conditions could also occur when two people edit the same document simultaneously. A document control system is needed to prevent this from happening.
To handle all these issues, you need a good document management system that at least allows for:
- Sharing of documents among people with the ability to view and edit them.
- Only one person to edit the document at a time.
- Fetching the most recent version of the document.
- Fetching specific versions of a document by date or version number.
- Searching documents for tags, keywords and such items.
- Comparison of two versions of a document to see changes and their context.
What sort of documents should you put in your document management system? Everything. As much relevant information on the project as possible should be stored for future reference. Meetings and phone calls usually are difficult to record electronically, but quick summaries can be written up, sent to all involved and stored. That way, you can also find out if everyone is on the same page.
Since a lot of information is passed around via email, you may want to create an email address for the project and CC all project-related mail to it. That way you have an easy way of storing such information.
To make project email easy to find for your team members, you could prefix subjects with an identifier. If you were working on an application named 'Walkr', for example, your subject line could read:
[Walkr] Next week's meeting has been postponed because of the public holiday.
You could go a step further and refine the identifier by adding classes of messages like
Test for testing tasks or
Dev for development tasks. Another strategy is to use keywords in the message body like so:
You can then search for the string
Key: Bugs to find mail on bugs. Email distribution could also be sped up with user groups for the relevant audiences.
Source code is different from other types of documents. It is much more subject to change than the others. It is also generally line-oriented (at least for the developers) in that change to a particular line doesn't affect the lines around it. If you edit line 149, the control system should only flag that that line has changed. This isn't the case with other types of control systems where the affected words would be flagged instead.
These mean that separate tools should be used to manage source code. A good system should allow all developers to use the code while preventing race conditions.
Code needs to be understandable to human beings. It should, therefore, have good documentation, both in design documents and code comments. You should give future readers of the code breadcrumbs to follow your thought process. The documentation should include the high- and low-level documentation that you can store in your document repository. You could build a method, for example, test it, and then write comments.
At some point, you'll need to prepare documentation that describes the application. They may be user manuals, cheat sheets, quick start guides, etc. You may also need to create video, screencast or other forms of multimedia versions of the documentation. All these can be stored in an archive. Make sure you don't start work on them too late in the schedule as well. If you wait until the last minute, users may not be able to use the application when its ready.