Lack of Documentation
July 24, 2008
Lack of documentation is very common; and is seen even in medium to large teams. For the small teams; it is understandable; you usually don’t have enough resources (human, time, finance) and to cover this; here are few suggestions
Requirement Gathering & Analysis
Create a mailing list for the project and make your team part of it. Discuss your requirement over emails/threads; and assign one person to send a periodic email/post summarizing the discussions. The last such email/post will lead you to requirement specifications.
Project Plan
Ask your team to divide the project into components and give estimated dead line. Do this again on the email list. Once done; write the summary for every commitment; discuss it in a thread. The last such email will be your project plan. Rewrite this in a new email; and then keep posting the replies to this whenever there is any change in the plan. Each reply should contain up to date commitments.
Design / Implementation
I strongly recommend using Sharepoint or other such web enabled collaboration platform. Write your design/implementation documents there. On each deadline/milestone; take a snapshot of current versions of documents/artifacts; mentioned below
- Database
Use diagramming support of modern database engines; SQL Server supports this. Your diagram will be up to date always.
- Design
Encourage your team to use contract driven development; use interfaces (interface IFunctinoality {}). Your design artifacts can then easily be created using some round-trip modeling tools like Borland’s Together or Rational’s XDE
- Implementation
Encourage your team to at least mention WIKI/Sharepoint URLs in the comments. Modern IDEs (like Visual Studio) has built in browser and you can easily correlate code with the documentation.
Data Layer
Use approach of least access; in database access layer; keep separate logins for developer’s access (SQL Server’s Enterprise Manager / Query Analyzer) and your application access. The developer login can have full access to the database but the login being used for the application should have least access. This way seeing which objects the application login has access will leads you to dependency information. It’s also suggested to write auditing code in stored procedures; so that you can pin point “dormant objects” easily.
Middle Layer
Encourage your team to log method names, parameters being passed and backend (sql query or web service name/url) being used in each method. Such log file will lead you to the dependency information. Audit these log files; and to check bottle necks.
User Interface Layer
Use patterns like Model view presentation; the view interfaces will help you to keep things in control and reflect changes across user interface and middle layer easily. Counts of such interfaces will also help you estimate the size of your application.
More…
Use emails; encourage your team, not to leave the office/workplace unless a status of what has been done and what you will do the next day is informed to the project email list. The team lead should write periodic emails for “To Dos” and “Status” such emails will help you write status summaries for the management.
Also encourage your team to write postmortems on each milestone or on periodic basis. Let them write what they feel and wish. Keep such email threads separate; they will help you to improve your processes for the next project.
The Scrum
July 24, 2008
SCRUM has been successfully employed by hundreds of different companies in many different fields, with outstanding results.
SCRUM is a loose set of guidelines that govern the development process of a product, from its design stages to its completion. It aims to cure some common failures of the typical development process, such as:
- Chaos due to changing requirements – the real or perceived requirements of a project usually change drastically from the time the product is designed to when it is released. Under most product development methods, all design is done at the beginning of the project, and then no changes are allowed for or made when the requirements change.
- Unrealistic estimates of time, cost, and quality of the product – the project management and the developers tend to underestimate how much time and resources a project will take, and how much functionality can be produced within those constraints. In actuality, this usually cannot be accurately predicted at the beginning of the development cycle.
- Developers are forced to lie about how the project is progressing – When management underestimates the time and cost needed to reach a certain level of quality, the developers must either lie about how much progress has been made on the product, or face the indignation of the management.
The SCRUM values are derived from the Agile values of software development.
- Individuals and interactions over processes and tools – processes and tools are helpful, but they will do you no good if the team does not communicate and collaborate in a constructive fashion.
- Working software over comprehensive documentation – documentation is important, but what’s most important is to have working software.
- Customer collaboration over contract negotiation – you are not just looking to get a contract and get money that way – you are solving the customer’s problem.
- Responding to change over following a plan – if the requirements or perceived requirements changed, so should the plans and design.
The scrum process has 3 main phases.
In this phase, the project is planned and high-level design decisions are made.
Figure 1: The SCRUM Sprint Cycle
The sprint cycle is an iterative cycle of about 3-4 weeks, in which the actual development of the product is done. It starts out with a Sprint Planning Meeting to decide what will be done in the current sprint. Then the development is done. A sprint is closed with a Sprint Review Meeting where the progress made in the last sprint is demonstrated, the sprint is reviewed, and adjustments are made to the project as necessary.
The sprint cycle is repeated until the product’s development is complete. The product is complete when the variables of time, quality, competition, and cost are at a balance.
- Develop the product further – implement, test, and document.
- Wrap up the work – get it ready to be evaluated and integrated.
- Review the work done in this sprint.
- Adjust for any changes in requirements or plans.
In this phase, the product’s development is brought to a close, and the product is released.
The SCRUM team consists of 2 groups – the interested team, which consists of people who are interested, but who will not be doing the work, and the working team – people who are interested, and will be doing the work on the project.
A team typically has no more than 6-9 working members, although SCRUM has been successfully used with more members. If there are more members than manageable, the project should be broken into multiple sub-projects, each focusing on one, self-contained area of work (one for QA, one for documentation, etc.). There should be people to act as bridges – that is, to attend the meetings of more than one SCRUM team, and act as a communication bridge between the teams. Members of teams that are closely related/involved with each other should sit in on the other teams’ SCRUM meetings.
The team’s leader is called the Scrum Master. He should be one of the members of the working team – that is, he should be one of the people who is actually doing the work on the project. The SCRUM Master measures progress, removes impediments, and leads the team meetings.
The product is developed in a series of 1-to-4-week iterations, or sprints. Before a sprint is begun, a Sprint Planning Meeting is held to determine what features are to be implemented in that sprint. The sprint has 4 major steps:
- Develop the product further – implement, test, and document.
- Wrap up the work – get it ready to be evaluated and integrated.
- Review the work done in this sprint.
- Adjust for any changes in requirements or plans.
A prioritized list of all the desired changes to the product being developed, put together by the product owner. See Figure 2.
A list with items that will be completed in the current sprint, taken from the product backlog. See Figure 2.
A 15-minute SCRUM meeting is held every day. The SCRUM Master asks the three questions, and all members of the team and interested parties take part and give feedback. The meeting should be held at the same place every time, so that people know where to go.
Impediments are things that get in the way of the progress of the project. The SCRUM Master is responsible to look for and remove these obstacles so that they do not slow down or impair the project.
The Scrum Master asks the developers 3 important questions at every SCRUM meeting:
- What have you accomplished since the last meeting?
- Are there any obstacles in the way of meeting your goal?
- What will you accomplish before the next meeting?
The person who commissions the project, and defines the requirements and priorities for the product.
A meeting at the beginning of a sprint where the sprint is planned. Items from the Product Backlog are selected to be completed in the sprint, based on the priorities set by the Product Owner.
A sprint is closed with a Sprint Review Meeting where the progress made in the last sprint is demonstrated, the sprint is reviewed, and adjustments are made to the project as necessary.
[to be continued...J]
