One of the most challenging parts of managing a staff is ensuring you communicate clearly, both within your division and within your organization. When I moved a group of 24 developers from a very procedural programming paradigm to an object-oriented paradigm, it became clear that the hierarchical way we had been communicating just wouldn’t work.

We were struggling with trying to hold frequent meetings and update sessions to keep everyone on the same page. It became apparent that the following communication issues were at the core of the problem:

  • We were handling a rapidly growing number of requests from throughout the organization for updates on projects and information about our paradigm shift.
  • We were dealing with a paper-based system that forced us to compile and transport the information in a large binder.
  • We needed to maintain historical documents.
  • We had to meet the requirements of an annual audit of our processes and documentation.
  • We needed to eliminate the duplication contained in reports created by managers and developers.

We needed a way out of this consuming data spiral. In this article, I explain how we structured our intranet site to tame the communications/paperwork beast.

Trimming the workload and improving communication
The intranet site we set up helped us reduce calls for project status information to my project leads and myself by approximately 60 percent. Further, meeting the requirements of an annual audit, a chore that had taken 2.5 developer weeks to complete, was greatly streamlined. Utilizing the data housed in the intranet allowed us to cut audit preparation to about eight developer hours, a 92 percent decrease. And developers, using a wireless system, were able to use laptops and desktops to access project information in real time.

Helping everyone understand the process
The methodology section of the site was the first to go up. Because we were just beginning to solidify our commitment to a rigorous development process, there were lots of questions both from IT and other departments about our new process. We designed the intranet to answer these questions.

The main intranet page included a graphical look at the process using a series of images which linked to elements of the process, including the details of each step and a narrative outlining the roles played by different members of the project team.

The documentation required for the process was indexed by a document template, in both HTML and word processing formats. Both include a full narrative to assist team members when they are filling out the documents.

Tracking current and completed projects
Another section of the intranet site listed current and completed projects. The overall progress of each project is tracked by a figure indicating the percentage of the project that is complete within each phase. I made it my job as a manager to update this section, a strategy that forced me to analyze and understand the project reports.

Each project had its own Web site underneath this main project documentation site (see Figure A).

Figure A

Completing and documenting projects
The completed projects section of the site was the easiest to maintain. Once a project went into production, the project lead had one week to finalize documentation. Once finalized and approved by the manager, all team members’ write access was revoked. The only people who had write access were the manager and the Webmaster.

When completed, the project link was moved to the completed projects page. Since the team was using Java as our programming language of choice, we compiled a final JavaDoc for each project that used the appropriate JavaDoc comment delimiters within the code, making it easy to create and view comments.

Creating a common code and JavaDoc repository
Finally, we maintained a common repository of code and JavaDoc. Completed projects were zipped up, along with deployment documentation, into a final project archive as a backup to our code repository. The documents in this archive included the JavaDoc for each project, Since JavaDoc is entirely HTML, documents could be easily integrated into our documentation site and searched.