The Importance of
Documenting Discipline in IT Projects
Marlene Sánchez – IT Architect
July 2013
Have you ask yourself what is the real
importance of documenting a design, process or architecture? Do you imagine installing
the electrical system in your house without proper documentation? Do you think
chances of failure increase due to lack of documentation? Honestly, I hope that
in some point of your career you have asked yourself these questions since from
my perspective; a“Documenting Discipline” is a practice as important as constructing
a final work product or delivering an IT service.
In a nutshell, the present publication aims to
explain: 1) Facts and Reflections of the “Documenting Discipline” in IT
projects 2) The consequences of lack of practicing this discipline 3) The importance
and benefits of documenting; and finally provide recommendations to project
managers and team leaders to promote this discipline.
Facts and Reflections of
the Documenting Discipline in IT Projects
In my 13th year IT professional and 5th year as
System, Architect, I have witnessed a generalized problem with the discipline
of documentation in all Mexican teams with whom I have the opportunity to work.
Indeed based my observations I have proved the fact that 9 of 10 professionals
prefer to reanalyze similar problems they face, instead of documenting the resolution
process one time and then reuse it in future situations. No matter if the
professional is a software programmer, an analyst, consultant or architect; professionals
by themselves don´t want to spend time documenting.
So after these observations, I began to question
myself, why IT professionals act in that way. And after some years of
observations and sharing ideas with my colleagues, I came to the following reflections
about IT professionals: 1) Professionals
don´t perceive that documenting is useful in their work since they believe they
can handle all information in their heads 2) Professionals use to be in a hurry
due to bad planning and certainly they prefer to finish their work instead of
document it 3) Professionals find documentation boring and don´t know how to produce
usable documentation 4) Professionals minimize the impact of not documenting
due to lack of knowledge of the implications of not doing it and 5) Team
Leaders/Managers don´t promote the usage of an established methodology and
don´t specify which work products must be documented, so professionals don´t
have a clear vision of what to document.
Now regarding the previous behavior, you may think
that it is a problem of education, lack of training or bad planning, isn´t it?
However, I believe that this could be a combination of the three plus additional
factors that are enterprise specific like: management practice and internal
policies since in some cases: 1) projects use to be sold without a plan that specifies
time for documentation and 2) Team leaders/managers don´t promote documentation
practices as standards in all projects. The
following cases not only will expose the rationale behind these behavior problems
but they also will reveal the consequences of not having a documentation practice
in place.
Consequences due to
Lack of Documentation Discipline
To illustrate the consequences of lack of
documentation discipline, I´m going to use two examples: 1) The case of a
Mexican firm part of the Retail Industry and 2) The case of a transnational consulting
firm. As you will notice, the first one hadn´t a documentation discipline
implemented while the second had one in place but it was not followed by
Project Managers.
Case 1: Retail Industry Firm
In the case of the Retail Firm, its IT
department was focused on custom development and operated without formal
documentation procedures. Architecture, designs and code blueprints were not
available to developers so the following problems were recurrently present:
- Wasted Development Time and Code Duplication were constantly present since developers didn´t know which components exist in the application and they use to construct new work products from scratch
- Architecture decisions were not easily taken since there were no documentation of the AS-IS architecture
- . Artifacts´ (i.e. processes, software components) Improvements were not possible since developers and architects didn´t have an idea of how artifacts were constructed and with which rationale
In this regard, the department´s head was worried
to solve urgent day to day development problems instead of identifying the real
cause of deadline delays, which in part was the lack of maturity in its
development and documentation processes. In this scenario, developers were not
trained to appreciate the value of documenting their work and code was a black
box that should be analyzed when it needed to be modified.
Case 2: Consulting
Firm
Problems due to Lack of Documentation Discipline
are also present in firms that offer technology consulting services, even if
they own specific methodologies to deliver those services. Indeed, the
consulting firm of this example was trying to deliver a system integration
project to another big corporation in Mexico City, however the management team
was not following the firm´s formal methodology to accelerate the
implementation and as a consequence, no documentation discipline was promoted which caused the following problems:
- Operational environments (e.g. DEV/QA/PROD) were not installed with the same installation characteristics given that formal documentation of previous installation procedures were not created on time or shared to infrastructure team which caused inconsistencies in the implementation and design phases
- Configurable Master data and business rules in “Out of the Box” applications were not replicated to all environments due to lack of documentation discipline which caused delay and rework on testing phase
- No Knowledge Management strategy was defined and transferred to teams’ members that were part of the project, so documentation was out of date, incomplete and not exposed to other team members
Now, since the project was weak in documentation
discipline and staff rotation was high, knowledge was lost when a new
administration take control of the project which also caused delay project
plans and monetary losses.
Importance and Benefits
of Documenting
So, after considering the impacts of not having
a Documenting Discipline, it becomes evident that the practice of documenting could
bring the following advantages to IT professionals and IT Projects:
- Ease of decision making regarding architecture, designs, processes, or other artifacts that could be involved on the development/delivery process
- Delays of project schedule could be avoided if documentation is available and is useful to all team members
- Improvement of artifacts is easier given that team members could have a broader view of the system/process/design
- Time save is possible in application development since components could be reused or modified when needed and not duplicated
- And finally, On boarding process of new staff is accelerated when documentation is present
Recommendations to
promote the “Documenting Discipline”
And now knowing the benefits that a Documenting
Discipline can bring to IT projects and professionals, I share the following recommendations
that will help firms/teams to promote the discipline of documentation.
- Methodology of deliver/development must define specific work products and must recommend which ones are mandatory depending on the case
- Firms must look for a good level of maturity in their IT processes (i.e. CMMI level 3, 4 or 5) and managers must follow these processes in all IT projects respecting the deliverables that are mandatory in order to promote documentation discipline
- Teams must define documentation templates that must be standardized, used and understood by all team members in order to create mutual understanding
- Documentation Staff must be present in all IT projects in order to: 1) make sure that all mandatory artifacts are documented 2) prepare documentation with team members 3) Explain the Knowledge Management process to all team members
- Peter Harrison1, an author of Linux books recommends the creation of documentation projects to formalize the discipline which I have had the opportunity to implement in several projects and which works perfectly fine if a Knowledge Management initiative is in place
- And finally, documentation practice must be encouraged by managers, team leaders and enterprises and performed by professionals in a discipline way in order to obtain beneficial results. For instance, in custom development project it is recommended to implement a methodology like PSP (Personal Software Processes) in order to educate their staff on the benefits that documentation can bring to their work.
Conclusion
In conclusion, it is clear that IT companies and
IT Leaders can obtain tangible benefits of a Documenting Discipline. However, implementing
a Documentation initiative requires a change of mindset of people all over the
company which represent a challenge, but not doing it will always represent a
risk on any new project that want to be started. Think about it, can this initiative
diminish your project´s technical debt?
References
[1] Peter Harrison, Linux admin fixes: Lack of
documentation, http://searchcio-midmarket.techtarget.com/tip/Linux-admin-fixes-Lack-of-documentation
