Advantages of Planning a Project

Planning the documentation project helps you in the following ways:

Reaching an Agreement

  • You can consider all the aspects of the documentation efforts when you plan it. You can think over the project and make all the decisions up front, rather than as you write. So you have all the agreement on the approach to document setup before you start writing.
  • If the project involves more than one writer, you can get an agreement from them regarding their responsibilities on what you intend to do, so that all are clear about their part in the project. Difference in views can be taken care of in the initial stages of the documentation effort.

Formalizing Certain Aspects

Planning helps in formalizing the following components:
• Project goals and objectives.
• Scope and expectations of the document.
• Roles and responsibilities of the team members.
• Assumptions and constraints.
• Quality management approach.
• Project management approach.
• Ground rules for the project (anything that is different than usual).

These can be grouped into separate topics in the documentation project plan.

Uncovering Problems

For large documentation project, as you start planning it in detail, you will uncover the problems before you start writing the document.

  • The plan will help answer questions regarding what goes into the manual, where it is to be added, the style to be used, etc.
  • You can avoid doing/redoing some tasks if you anticipate certain problems at the starting of the project.
  • It saves hours of rework or delay which germinates from unclear goals and missing information.
  • You have time to look for and decide alternate course of actions.
  • You can plan some buffer time for solving problems, right at the planning stage.

Documentation Process: Importance

When something goes wrong in a project, it is easy to blame an individual as the cause of the problem or for deviating from the desired quality, process, or schedule. This is where procedures help. Procedures are nothing but standard approach of doing things.

A good process is akin to a highway. Though it is made to ensure smooth and fast travel, there is a likelihood of head-on collisions with vehicles coming from the opposite direction, at certain junctions. Keeping an eye open for such junctions and having considerable room to manuver within the cross roads avoids collisions. Similarly, you have to explore and define each of the areas prone to accidents and collisions during the planning process.

Manuals have a bad reputation, often for good reason. The good documents don’t get the credit they deserve because the bad one gets all the attention. The worst part is that writers get the blame, even when they are given inadequate time, tools, and support to do the job. — Michael Bremer

Problems like unclear procedures, inadequate information, language errors, and, online help that is difficult to navigate, lead to inefficiency and reduced productivity of the users. So it is important to have an effective process that will help reduce errors and improve usability of the documents. It is not enough to say that the document must be error free. It is equally important to define the acceptable quality, and the methods to meet it. Hence, the documentation effort should also be well planned, not just thrown together at the last minute to meet a deadline.

An effective documentation process helps reducing the problems as it:

  • Defines the practical steps you must perform to achieve quality results.
  • Contains a list of tasks to be performed.
  • Provide a framework on how to perform the tasks and activities.
  • Defines the accepted degree of accuracy and errors and thus increases the likelihood of success of a project.
  • Explains the set of activities to be carried to efficiently complete a quality documentation project.
  • Specifies the tasks, objectives, roles, responsibilities, process description, references, quality records, and authorization details.
  • Provides confidence that the work done in a certain way is acceptable.
  • Provides consistency of results—if everyone follows the same process and procedure, they will be doing things the same way, reducing the probability of making errors.
  • Provides a ready-made reference to a newcomer and thus reduces the learning curve.

Limitations of Procedure/Process

Processes do not make mistakes. People do. Processes are the tools that help you avoid make the mistakes. Inspite of all the advantages, these are some limitation of the procedures and processes:

  • A process may work well for some projects/products, but not for the others. In such a situation, it is better to adapt to an alternative workable variation in the process than to blindly follow the prescribed procedure. Sometimes you may have to perform some additional tasks not listed in the process, and sometimes you may need not follow all of them.
  • Although the process describes how certain activities should occur and be performed, sometimes experience helps you make the right decision. Experience also helps you understand the issues to make good judgment on how to proceed, specially in unknown situations that are not addressed by the procedures

Importance of Project Plan

Planning is the most important aspect of a documentation project. A good plan provides a basis for every action that needs to be performed. It helps you frame the projects so that you can work towards a goal. It is very unfortunate that in most organizations, documentation planning is usually regarded as something to be done after the development phase is complete.

Careful analysis and planning are integral parts of the working life of a technical writer. You cannot have quality in a project which is not properly defined and/or planned. You need a predefined structure to produce quality documents in a predictable and reliable manner. Though the basic approach may remain the same, the planning process may vary for organization to organization. To produce an useful documentation, consider it to be an integral part of the product development phase.

The trouble with plans is that they are based on the way things are now. To be successful, your plan must focus on what you want, not what you have. —Nido Qubein

Very often, projects change so much that you diverge from the original plan as youprogress. So, planning at an initial stage may sometimes seem to be a waste of time,but no one can deny that it works as a road map that points to a destination. You canalways change it as you develop the document.

  • As soon as you get a project in hand, the temptation is to start writing. Starting immediately is the worst thing to do because you are more likely to hit the writers block and wonder what to write and how to write. In the process, you will end up with a poorly written document.
  • Sometimes, the project may get into such slippery grounds that you are not sure about what is happening and what is to be done. In such confusion, you can refer to the plan and get right back on the track.
  • The plan enables various people in a project to agree upon the contents, design, and other such details of the project before starting the documentation efforts. The product and documentation managers agree and approve of the way you intend to handle the documentation.
  • The plan is a formal agreement between the project manager, documentation manager, writers, and reviewers regarding the dates, formats, and other issues. Create the plan and get it reviewed and approved by the people involved in the project. This way, the management is aware of the effort that will go into creating the document and you will also have their agreement on certain aspects of the project.

What is Postmortem Meeting?

According to the dictionary, postmortem means an examination of a body after death to determine the cause of death or the character and extent of changes produced by disease. It can also be defined as a critical examination, evaluation, or assessment of someone or something past. Based on this definition, we can define postmortem as an examination of the project after it is complete to determine the cause of problems and delays, and ways of avoiding them in the future.

  • Postmortem of the project is the last step performed to evaluate the effectiveness of the documentation process. This basically means that the project has to be looked at in detail for the following information to do away with any possible mistakes in the future:

                        – Evaluate what worked and what did not.
                        – Identify the problem areas and processes.
                        –  Identify areas and/or processes that worked well.
                        – Look for a working solution that can be applied to the future projects.

  • It is a case study that provides practical help in understanding why problems or mistakes occur and how they can be avoided. Documenting your problems and solutions is the best way to develop best practices.
  • It is the comparison of actual performance with your plan. You can’t afford to repeat the mistakes and encounter the same problems project after project.
  • It is a process of looking at the current process, identifying what went wrong, and situations that weren’t working right. You can then analyze the situation, check how such problems and situations can be prevented in the future projects and come up with appropriate alternate solutions.
  • It is a practical method that helps you capture experience and collect suggestions for improvement from completed projects. It is also about identifying the positive and strong aspects of the projects and applying it to the future projects.

There is a famous quote by George Santayana, “Those who do not remember the past are condemned to repeat it.”

The same applies here as well. In short, the postmortem of a project actually allows you to learn from your mistakes. After any documentation project (big or small), you should step back and look at all the aspects of the documen the good, the bad, and the ugly. This will give you a proper direction to move ahead. So postmortem is not just about looking back, but is about looking back so that you can move ahead with ease and double confidence.

It is important to look back at what went right and what went wrong during a project and to share this information with others in the group/team. Continue following the procedures which worked well and try to nd solution and/or work arounds for problematic areas. Postmortem is the comparison of actual performance with your plan. It provides the opportunity for us to learn how to proceed with future documentation in a better way.

Why Have a Postmortem

When a project goes sour, it is natural to have bruised egos, and low levels of self confidence. In such a situation, the writer is blamed for deviating from the required quality or the schedule. There might be a person or persons at the point where something went wrong, but anyone in the position would have made the same decision, or failed in the analysis. It is the ill fate of the person(s) who happened to be there at that point of time. Most of these problems can be eliminated easily by improving the process.

In such a situation, you may desperately want to put the bad experience behind you and move on. Having such a meetings will help you and the project members discuss the experiences openly you can review what went wrong and what went right. You can find solutions to the problems and apply the lessons learned to the future projects.

If the projects should start with a kicko meeting, it is but natural that it should wrap up with a postmortem meeting. Having a postmortem meeting after every single project will help you gain more value out of the experiences. It improves the functioning for the next project. Hence postmortem has to be an integral part of the documentation process. It will help you collect valuable information about the problems you faced and the project in general.

Goals of a Postmortem Meeting

The project is over and is probably alive as a huge success and the writers involved are either excited about  the success and the positive outcome of their efforts or dazed at the negative results inspite of the hard work and effort they put in. The latter might be nursing a bruised ego. Is it necessary to talk of postmortem? Sure it is, because this is an extremely productive method of improving your documentation practices. The goals of the postmortem meeting is to:

  • Provide an environment that supports constructive criticism.
  •  Identify the loopholes in the project.
  • Encourage improvement in procedures and processes.
  • Encourage the project members (writers, developers, engineers, SMEs, managers, QA personnel, etc.) to share lessons learned the hard way.
  • Help to draw meaningful conclusions from the results of the previous projects.
  • Help you learn from your successes and failures.
  • Provide a process that allows you to identify some activities as best policies and adapt them in the future projects.
  • Support easy collection and archival of information.

Postmortem is intended to be an exercise which will help you realize more about how you work and help you make decisions about how to work more e ectively. You can identify some of the activities or processes that worked well and you can continue with, and problematic areas that you can avoid in the future.

Postmortem Meeting: Guidelines (Part II)

11. Did You Manage the Change

Documentation by default is prone to changes. Here, we discuss the unexpected changes:

  • Did unanticipated changes occur in the project?
  • Did you encounter any problem that you had not forseen or taken into account?
  • How did you respond to such problems?
  • Did you have a risk management system in place?
  • Did you have an alternative method to do certain tasks?
  • Did the documentation su er from excessive change of features of the product?

12. What Went Right?

Having dealt with the wrongs, problems, and errors, it is time to deal with the rights.

  • What went right with your project?
  • What are the areas that went on as you had planned and/or anticipated?
  • Where did you beat your estimates?
  • Did the document turn out well despite all the problems that you encountered?
  • Problems for which you had alternative approaches or appropriate solutions.

13. Focus on the Facts

The meeting should not discuss personality or mistake made by any particular participant. It should address the outcome of the project, suggestion for changes to the processes, and alternative methods to perform certain activities. People often react to situations in di erent ways. Different interpretations may cause hard feelings and bruised ego. Hence focus on project related facts and don’t blame individuals.

Wrong: This mistake happened because Ram did not perform the XYZ task.

Better: We would not have made this mistake it we performed the XYZ task.

Note here that the blame on we, not Ram. However at a later stage, the documentation manager or the team leader should talk to Ram regarding this problem in a personal meeting.

14. Create a Report

For maximum benefits, compile the lessons learned from your meeting and create a postmortem report. The report can include the following information:

  • The project information (overview of the project, estimated resources, tools, project schedules, milestones, effort estimates, etc.).
  • Differences in the initial plan and the final plan.
  • What went wrong and how it could have been avoided.
  • Anything that went wrong, but was corrected and taken care of on time.
  • Recommendations for implementing the lessons learned.
  • Any change in the existing process that will be helpful.
  • Alternative approaches of doing certain tasks.

15. List the Lessons Learned

After analyzing the projects, make a list of lessons you learned form the project. For this ask a few questions:

  • What did you learn from those mistakes?
  • Did you nd alternative methods to perform these tasks?
  • Did you find solutions to the problem you had?
  • Where can you apply these solutions and alternate approaches to future projects?
  • Is there any specific factor that you have to change in the process to make the project work better?

The answers to these questions will be the lessons you have learned while working on the entire documentation process.

16. Don’t Ask Demoralizing Questions

The success of a postmortem depends on the manner it is handled. Asking for information in the appropriate way minimizes the risk of blaming or demoralizing the team members. So, frame the questions appropriately.

Wrong: Rita, how did this happen?

Better: How did this happen? How can we avoid such a mistake?

In this manner the managers can give the the writer who made the mistake an opportunity to speak up, share the problems and issues faced, and explain the situation in which it happened. It is a healthy process if the writers are able to self identify the mistakes and own up rather than others pointing ngers at them.

17. Rephrase the Answers Accordingly

When participants in the meeting describe the facts related to problems, those answerscould blame other team members. These answers can be rephrased to communicate the same thing in a better manner.

Wrong: You said you were too busy with your project and could not concentrate on the edits.

Better: We must make the editing a formalized process. It might reduce the possibilities of errors!

This response suggests a solution to the actual problem, without targeting at a particular person. It also informs the writer in a very mild way to take peer-edits seriously. If need be, the manager or the project manager can have a formal talk with the concerned writer on a one-to-one basis.

18. Don’t Take Comments Personally

There can be two outcomes (good or bad) of any project you handle. Similarly, there are two ways you can react at the postmortem meeting. Whatever happens, do not let it a affect you deeply. If any of the team members takes any comment personally, discontinue the meeting until they can handle it in a positive manner.

  • If things go well, you should feel pleased that you have done a good job, but let your feet be firm on the ground. Try to do better the next time.Remember, you had the support of the team members who helped you do your work in a better way by giving you the right advice, by helping you with tools, by informally editing your work, by helping you to clear some issues, and by sharing your workload.
  • If things don’t go well, take it to heart just enough to make you a stronger person. Try to learn from your mistakes and try harder not to repeat them the next time (that is, you should try to avoid those mistakes). If you take it to heart, you will suffer lowered performance, lack of trust, bitterness, betrayal, and a lowered self-esteem.

19. Create Action Items

The postmortem meeting will not be of any use if you are not able to define some core action items. These action items should address the key lessons from the project. For each action item, clearly define an owner and time-line for completion. You can add statements as shown in the following table:

 
 

Holding a postmortem will only be successful if you are prepared, follow a clear agenda, and execute the action items resulting from the meeting.

20. Act on the Conclusions

Turn the knowledge you have collected into action plans and try to incorporate it into your project processes and methodologies. It is a productive way of closing a project because you actually gain enriching experience. Don’t get the e ort in getting people together, documenting experiences, creating action items, and a project postmortem report go wasted by forgetting to act on the conclusions of the report.

An action plan that doesn’t lead to concrete actions is useless.

Postmortem Meetings: Guidelines (Part 1)

Postmortem is touchy issue, but if handled well, it is an enriching process as you can discuss and document all the personal and professional growth you have experienced during the project. You can have a postmortem meeting that improves how you and your team manage projects, or you can have a meeting that demotivates and demoralizes you. The result depends entirely on the spirit with which you take it.

Take it in the right spirits, and you emerge out as a better and seasoned writer. This will help your from repeating the mistakes that can be avoided. This section describes what to do during the postmortem meeting so that it will help you to get the most out of this process. It also describes the guidelines for conducting productive meetings.

1. Don’t Delay the Meeting

The best time to conduct a postmortem is about a week or two after a product is released. This allows you to regain your thoughts good, bad, and ugly about the project without forgetting the details. It gives you enough time to think back and collect your thoughts.

The right time to have such a meeting is when the successes, problems, and mistakes are still fresh in mind. It is the ideal time to discuss what went right and what went wrong. You will be able to see the project as a whole, rather than focusing on the most recent activities of the project (which is fresh in mind).

2. Involve All Contributors

Involve all the contributers of the project in this meeting.

  • Collective meeting: This should involve all the contributers from the various teams (development, testing, documentation, and support engineers, etc.). This could be a generic meeting where you discuss the entire process of the SDLC and the DDL.
  • Team meeting: You also have to arrange a separate project review meeting with everybody in the documentation team who were involved in the project (writers, editor, team/project leader, and documentation manager) to reflect on the project experience.
  • This will give you an opportunity to discuss the documentation specific problems, issues, process, and suggestions for changes.

In either case, note down all the problematic areas and solicit ideas for improving or changing them in the future projects.

4. Use Review Forms

Most of the organizations use a project review questionnaire, which includes a 1-10 rating system to quantify subjective feedback. It contains questions for specific areas that might need improvement and use a comments section for open-ended feedback. A series of postmortem can ultimately evolve into a valuable project review form and use it to record your hard-earned wisdom. Later, a consolidated report should be put up for every one to see, read, and use.

5. Have a Clear Agenda

A planned meeting will help in including all the areas of concerns you may want to discuss and you can get the most out of the postmortem meeting. Certain factors you can focus on while creating an agenda are:

      • Project planning.
      • The processes followed by the different teams.
      • Communication between the team members and between different teams.
      • Clarity of roles within and outside the team.

Project Planning and Process

Look at the success or failure of the project plan, identi ed risks, and the schedules.

  • Were you able to accurately estimate the time required for tasks?
  • Did you coordinate the activities and tasks well?
  • Did you follow the sequence of the tasks effectively?
  • Did you come to a clear consensus as to which tasks had the highest priority?
  • What is the main reason for not meeting the deadline?
  • Were the risk factors taken into consideration during the planning phase? 

Communication

 Examine how well the project members communicated with each other.

  • Were the goals for the project clear to all the teams?
  • Were team members accessible to each other to help answer questions?
  • Did the team come to consensus about the decisions impacting the document?
  • Did the group respect the expertise of the team members and use them productively without disturbing them?
  • Did any team members have to wait for another team member to complete a task?
  • Were there any issues in communicating with colleagues outside the product team?
  • Were you kept in the loop regarding the changes to the product?
  • Was the communication regarding schedules clear?

 Clarity of Roles

 Explore how well roles were defined within the team and outside the team as well.

  •  Were roles within the team clear?
  • Was it clear who had decision-making power at every stage of the project?
  • Were the roles of the other team members known to you?
  • Were the priorities set for the project clear to you?
  • Did the members perform the functions necessary for the success of the project?

5. Don’t Look For Scapegoats

As a rule conduct positive and constructive meetings; do not look out for scapegoats.Postmortem meetings must be honest and should have an open communication. If you have any issues, raise them during the meeting rather than crib about it later. If a project has been diffcult or unsuccessful, expect some emotional venting. However, channelizing that in a constructive direction will benefit you and the team.

But, managers will have to confront non-performers. They will have to discuss it with the specific team member on a one-to-one basis regarding what went wrong and why, and areas for improvement.

6. Discuss What You Wanted to Achieve

Come prepared with your notes and observations for the meeting. Begin the review meetings by refreshing everyone on what you all initially thought the project to be and how you thought things would turn out. It would be helpful to include a brief overview of the project an estimated budget, resources, tools, project schedules (start and finish dates), milestones, and effort estimates.

Then, compare that information with what actually happened with the project. For example, you can compare the time frame and resources allotted to the project in the beginning (assuming ideal conditions) and the time and resources it actually took to complete the project.

7. Review Performance of Team Members

The postmortem meetings (when restricted to specific teams) can also act as performance reviews, because it happens right after the project. This will help you:

  • Focus on the skills that have to be improved or developed.
  • Focus on improving project strategies.
  • Understand the concept of self-review accurately.
  • Assess and improve performances.
  • Make changes to the way you do certain things to make the work process more effective.

The review should be done on a personal basis, where in managers can confront the writers who were at fault and tell them where they were wrong and why. Writers have to look at this as a learning process and learn to take such feedback gracefully.

8. What Went Wrong?

Focus on things that turned out worse than expected, especially the unexpected problems that crept in and took a wild turn. Also focus on problematic areas which you could control. Compile a list of the shortcomings and what went wrong with the project:

  • Were the problems anticipated?
  • Could you have avoided the problem?
  • What were the problems and diffculties that you encountered?
  • How well did you adhere to processes?
  • How accurate were your original estimates?
  • Did you deviate from the original estimates of the plan? If yes, why?
  • Where there any drastic changes in the plan?
  • What kinds of mistakes did you make?
  • What problems were unexpected, but solvable?
  • What issues were unexpected and extremely problematic?
  • Did the assumptions prove incorrect? Which ones did and which ones did not?
  • Were any targets missed?

Identify each and every problem, however small, insigni cant, and irrelevant it might seem to be. Try to nd answers for the the questions that arise with these questions which? why?, how? The answers will eventually help you improve.

9. Identify the Reasons

After identifying the problems, try to identify the reasons for those problem and for the change in the original plans, schedules, or processes. Is it because:

  • The plan was not accurate? or
  • The code changed very often? or
  • You did not receive information on time? or
  • The change in the development schedule? or
  • You were unaware of the last minute changes.

10.  Review the Risk Plans

Analyze the problems and issues faced during the project. More importantly, analyze and discuss the approach taken to come out of it:

  • Did you take risks or did you play it safe?
  • Did you encounter any problems or unpredicted risks?
  • Did you resolve them?
  • If yes, how did you do that?
  • If you did not, why did you not resolve them?

Pay particular attention to how you would change your approach for the next project. The approach should be what should I do in such a situation? Try to make a list of all the aspects that you should avoid that would create problems or hinder the flow of work. Also make a list of possible solutions to the anticipated problems.

Myths About Quality of Documents

There are several myths regarding the quality of documentation. Here, we will discuss a few common myths.

Myth 1: Quality is an Editorial Function

Quality is not just an editorial task. Writers should understand that the only way to improve quality is to prevent introduction of errors instead of xing them. Try to produce quality drafts, with as fewer editorial and technical errors as you possibly can. For this, you should be able to de ne and measure the quality of the document. This can be done by determining company-specific standards, styles, processes, and checklists that have to be rigidly implemented for all the documents.
 
Fact: Quality has to be taken into account in all the stages of the documentation process. 

Myth 2: Quality is Applied at the End of a Project

Technical writing is a meticulous process: gathering information, structuring information, writing, rewriting, reviewing, editing, quality checking, and production. Some of the tasks may have to be done a number of times. Letting reviewers nd mistakes in a document during the reviewing phase. It makes the entire review and rewriting phase a time consuming process. It also makes them form a negative opinion about the quality of the work produced by you.

Try to improve the quality of the document by improving the quality of the input i.e., by preventing the introduction of errors in documentation. For this, quality must be defined and then designed into the document, not evaluated only at the end of the writing phase. To achieve quality and hence customer satisfaction, you have to follow certain styles, formats, and processes to help you work in a more professional manner.

Don’t follow them mechanically, follow them to improve as a writer. This will help to produce documents that are usable and have a high level of quality.

Fact: Quality must be designed into a project, not evaluated only at the end. 

Myth 3: Writers are Responsible for Testing Documentation

Most of the organizations feel there is no need for testing documentation and justify that it is the writer’s responsibility to write an error free and quality document. According to them these aspects should be considered during the writing phase.

They feel that the edits and reviews take care of errors if any and hence there is no need for testing the document. For them, the idea of sparing time to test the documentation seem to be absolutely ridiculous, especially, when there is barely enough time to test the software/product. This usually happens in the following cases:

    • When the decisions of the documentation team is taken by a person who does not know about the technical writing concepts and issues.
    • The persons to whom the documentation manager reports to does not understand the requirements of the testing the documentation.
Fact: Writers are responsible for creating an error free document, but the QA and/or support engineers are responsible for performing the QA of the documents.
 
Myth 4: Only bad writers use standards and guidelines
 
Some technical writers feel that standards, guidelines and checklists are not for them because they are good writers. I remember an instance, wherein a trainee writer declared that she completely disagreed with the measures that are being put forward for quality control (using checklists, guidelines, etc.).

According to her, a system is no substitute for common sense and hence putting a system into place was useless. Now, wouldn’t that mean that all the technical writers around the globe are useless, because not only do they use various quality control systems for documentation, but recommend them as well. This shows how good some writers think themselves to be, but also shows how ignorant they are. What they need to understand is, using guidelines and checklists does  not question their writing skills.

    • It is a proven way of reducing errors and improving the quality of the documents
    • It helps in maintaining consistency in the documentation when multiple writers work on a single project.
    • It avoids unwanted discussions and arguments in deciding what was agreed upon sometime back.

If the writers themselves regard standards and guidelines as useless, we should not blame the others for doing so. Documentation standards is actually a formalized database of the decisions about quality related standard style, language, terminology, document structure, content, and format. Some of them are incorporated directly into word processor templates (font sizes, margins, page layout, indents, bullet formats, and so on).

Other standards (terminology, acronyms, abbreviations, capitalization of headings, preferred spellings, punctuation, and hyphenation) may need to be documented and used by the writers.

Fact: All the writers irrespective of their experience or position in the organization should make use of standards, guidelines, checklists, and follow quality control methods.