Technical Writing PM (Project Management)
Planning
In the planning phase the system is created on paper.
- Defining the proposed system
- Scope – setting the project boundaries
- Developing project plan – the what, when and who of the project
- Managing and monitoring the project plan – tracking and validation
Analysis
- Setting requirements - what are the tasks to make the system successful?
- Requirement analysis – create priorities and define them in a document.
Design
Creating the actual design of the project
- Design technical architecture – deciding the best technical designs to suit the needs of the project
- Design systems model – creating the graphical world of the project.
Development
Building the actual product
- Hardware – sourcing the materials needed to build the project
- Software – coding.
Testing
- Setting of test conditions - create a realistic test environment to eliminate bugs.
Implementation
The product is finished and ready for use by clients. This stage requires
- User training
Maintenance
Keeping the system in step with the client through:
- Customer Help Desk
- Updates
What is the Documentation Life Cycle?
Like all projects, documentation has a life cycle to guide the process.
The best description of the life cycle was produced by Precisely Write Inc, whose structure and approach is below.
Define
The definition stage asks key questions about what the project requires.
General Issues
- What is the objective of the document?
- Is there any existing documentation?
- Is there a similar product with documentation?
- How frequent are upgrades?
- Single sourcing?
Documentation Issues
- What type of documents are being created?
- Is there a preferred tool?
Audience Analysis
- Research
- User Goals
- Environment
Publication Issues
- How will information be distributed?
- Sizes used for hard copies
- How should the final copy be delivered?
- Will the document need translating?
Technical Direction
- Who are the SMEs and what are their positions?
- Is there a procedure for getting information?
- How do they view documentation?
Review Process
- How will the documentation be reviewed?
- Do developers allocate time to document review?
- How will user testing be performed?
- How will this affect the schedule?
- size matters
Scheduling
- What is the project timeline?
- How many reviews will there be?
- How do you handle deadline slips?
- What is the procedure for handling changes to the product which affect documentation?
Administrative Issues
- Project name
- Reporting structure
Design
The design stage is where the actual look of the document is decided, as well as what will be included and left out.
- How much detail is needed?
- Are there any company standards?
- Are there any industry or government standards/requirements? (Military manuals must meet certain Mil-Specs and commercial manuals may need to meet government or trade association standards)
- What sequence should the information be presented in?
- What elements are required for the document?
Develop
During the development stage, the document will take shape.
- Authoring
- Research
- Planning
- Naming conventions
- Version control
- Access control
- Template design as needed
- Authorization of template
- Develop authoring guidelines
- Develop training if applicable
Deliver
- What form will the final output be available in?
- hard copy
- CD
- webhelp
- Others
| SDLC | Phase | Documentation Life Cycle |
|---|---|---|
| idea for a new product | Initiation | should the product be documented and how? |
| feasibility study | Planning | type of document, objective |
| setting requirements | Analysis | audience analysis, scope of document, cost and schedule |
| technical architecture and software | Design | style of the document and Prepare SRS |
| sourcing materials and building the code | Development | research and writing |
| ensuring the products meet requirements | Testing | Complete, Correct, Consistent, Readable |
| ready for sale to clients | Implementation | prepare hard copies, CD-ROM, online, Delivery |
| support and upgrades | Maintenance | updates, archives, re-use |
Capability Maturity Model (CMM)
CMM stands for Capability Maturity Model, a tool for improving processes.
The tool was developed by Software Engineering Institute at Carnegie Mellon University in Pittsburgh.
Its aim is to help companies improve their processes and establish best practice in a company.
According to this tool, there are 5 possible levels of process maturity.
Level 1 - Initial
The most basic level of process management. Decisions are made ad hoc, meaning there is little planning and the company environment is unstable.
Success is a product of competent staff rather than established processes. Level 1 companies do succeed, but they miss deadlines and go over their budget.
Companies operating at level 1 rely on highly skilled staff to succeed.
Level 2 - Repeatable
A level 2 company has implemented some processes into their project management. In particular they track costs and time in projects.
By having disciplined processes the company continues with practices even when under stress.
By tracking time schedules, level 2 companies can keep projects on course with major milestones although there is still a tendency to complete the project late and over-budget.
In projects which are similar, level 2 companies can repeat their success.
Level 3 - Defined
In level 3 the company has standardised processes which are established and being improved. As a result, there is consistency across the company. Individual projects are defined according to company policy.
The company sets objectives in line with their standard processes.
Level 3 has a greater scope of standards and procedures than level 2. Because a level 3 company has standard processes, individual projects are in line with those standards rather than individually defined.
The company ensures good project management by using quality project management software.
Level 4 - Quantitatively Managed
At level 4, companies are using well defined processes to control the project.
Most importantly, company management have the skill to adapt processes to individual projects without negative outcomes.
Level 4 takes level 3 further by judging process performance by statistics and other metrics to predict results.
Level 5 - Optimized
At level 5 process performance is improved by the use of use innovative technologies.
Processes are measured against quantitive objectives, leading to improvement in both organisational standards and processes.
Possible improvements to processes are evaluated and implemented.
The company staff are aware of and identify with company values.
Learning is a vital part of the development of the company, the company quickly shares learning.
Level 5 differs from level 4 in dealing with the causes of process variation. Processes are then changed in order to improve the process.
More
For more detailed information about SEi and the CMM, visit www.sei.cmu.edu
“You can’t control what you can't measure” - Tom DeMarco
Metrics
Metrics are used to measure a number of variables throughout the project life cycle, including:
- productivity
- resources available and required
- trends
Metrics are used to create key productivity indicators - to show just how effective a company is on the market place.
Why use them?
Metrics are used not just to measure the productivity of a work force or project, but also to set targets.
In order to fully use metrics the following information about each metric is essential
| Element | Description |
|---|---|
| Metric | Name of the metric |
| Metric Description | Description of what is measured |
| Measurement Procedure | How is the metric measured |
| Measurement Frequency | How often is the measurement taken |
| Thresholds Estimation | How are the thresholds calculated |
| Current Thresholds | Current range of values considered normal for the metric |
| Target Value | Best possible value of the metric |
| Units | Units of measurement |
(Source of this table: ISM3)
Quantitative vs. Qualitative
There is a risk known as: "what you measure is what you get". If we count the number of pages, the chance is we get a huge amount of pages just to get a higher score. If we count words, it may happen to words, too.
The paradox is the properties of documentation that can be easy measured have little importance in regard to the real value of the document from the end user`s perspective. This is the case of counting the number of pages in the document.
Quantity is not Quality.
From the other side, it is more difficult to build a metrics for the attributes that in fact brings an added value to the document from the end user`s perspective. This is the case of: subject coverage by content, language style, enough level of details for the reader, etc...
Also, planning good metrics for the document quality must start at the phase of collecting requirements. If the document must be measurable then the requirements for the document must also be measurable. Only this way we can see if the requirements have been met by the writer and other players in the production chain. E.g. if the requirement is that we produce a good document, so how could we define the metric showing that the document is really good?
Requirements must be specific so that we know they are attainable. And the match between the content and requirements may be then used as one of the metrics used for measuring the document quality.
Other
Statistical information about peoples' work will be mined from CMS.
The management of workflow and supervision of all other activities will be based on those data.
All projects cost time and money.
It is important to accurately estimate how much a project will cost.
Most projects are late and more expensive than planned.
Cost and Time Estimates for Documentation
According to studies, documentation accounts for 10% of the total cost of a project.
Automated Estimating Systems
The use of automated estimating tools can greatly improve the accuracy of cost and schedule estimates, when compared to their human equivalents.
In most projects with a Function Point score of more than 10,000 the costs of documentation and defect removal are greater than that of creating the project itself.
Common Functions of Automated Estimating Tools
- Estimate time and cost at phase, activity and task level
- Makes adjustments for work periods, holidays and overtime
- Considers local salaries and workload
- Adjusts for project type
- Supports Function Point, LOC metrics or both
- Handles conversions between Function Point and LOC
- Supports new projects as well as maintenance and upgrade projects
Advanced Functions
- Estimates quality and reliability
- Analyses risk and value
- Estimates return on investment
- Shares data with other project management tools
- Assesses historical data according to measurement models
- Supports process assessments
- Provides statistical analysis for multiple projects
- Currency conversion for international projects
Variable Factors
As all projects are different, there are factors which change according to the project. A good automated estimating system will take these variables into account.
- Staff experience
- Client expectations
- Product type being developed
- Size of deliverables
- Project size
- Design method used
- Requirements method used
- Available re-usable materials
- Testing methods used
- Overtime status - paid/unpaid
Example Estimating Tools
Task Tracking
It is vital during a project to make sure that the necessary work is being done.
This process is known as "task tracking"
It is important to track tasks to ensure a project stays on time and within the budget.
Avoiding scope creep is another valuable use of tracking.
With the same products being used around the globe, it is important to adapt products to local markets particularly where the original comes from a different culture and language.
The abbreviations are based on taking the first and last letters of the word, using the lower case form, and the number of letters in between.
i18n - internationalisation
Internationalisation is a process for making software which supports all the world's languages.
Such software must also be aware of local cultural norms and traditions.
i18n is the first step in the process of making a product suitable for varying cultures and traditions.
L10n - localization
Once a product has been internationalized, the process of L10n can begin.
The aim of L10n is to make a product suitable for cultures other than the one it was created in.
L10n takes into account factors such as:
- language differences such as British and American English
- different alphabets - Cyrillic, Hebrew, Arabic, additions to Latin
- varying calendars - Islamic, Buddhist, Jewish, Gregorian etc.
- measurements - metric and imperial
- cultural traditions and customs
- religious holidays
g11n - globalization
Globalization is the process where companies sell their products in many markets around the globe.
It is this which has led to the need for l10n.
- L10n and i18n
- Internationalization and Localization
- Internationalization
- Documentation Life Cycle PDF
- SDLC
- Cost Estimating Methods for Large Projects
- Metrics
- Using Metrics to Plan Documentation Projects
Scope
The scope of a project is the total requirements and features of the project.
Scope can also refer to the amount of work required to successfully complete the project.
Why is it important?
Understanding the scope of a project is vital to keeping a project on track.
Without clear targets and procedures it is easy for a project to become large and unwieldy.
This is known as "scope creep" and has a major impact on both the financial and time costs of the project.
Controlling Scope Creep
Scope creep is the adding of features to a project which were not in the original plan.
There are 2 types of scope creep:
- Business Scope Creep - when requirements are added to a project to meet business needs.
- Features Scope Creep - when extra features are added to a project by developers independent of management.
To control scope creep it is necessary to have a Scope Management Plan which clearly defines the procedures the project will follow. The Scope Management Plan is part of the overall Project Management Plan.
Features which fall outside the scope of the project are not added to the project automatically but must be assessed to see if they fit the requirements of the project.
Design
The design stage is when decisions of how a project will look are taken.
In documentation, the design phase is about deciding the following:
- What will the document cover?
- What format will the document take?
- How will the document look?
- In what order will information be presented?
Why is design important?
The design stage must take into account the needs of the audience, in order to create something appropriate to their task.
- Goals
- Quality
- Schedule
- Cost
- Reuse
- Audiences
- Internal
- External
- Processes
- Research and content gathering
- Writing
- Graphics
- Editing and testing
- Publication
- Project Data
- Risks
- Pitfalls
- Avoiding pitfalls
What are milestones?
A milestone measures two things:
- When something should be done by
- How much progress should be made
Why are they used?
During the project milestones are used to track progress.
Milestones should be set when the requirements are established.
Milestones within a project are intended as a guide for personal workflow.
What is delivery?
The end result of the documentation process is delivering the prepared texts to the person who needs them.
Who do we deliver to?
Like every part of the process, delivery needs to be tracked to ensure that the material reaches its target.
Sometimes the person we deliver to is not the end user.
For example if we prepare a help file for an online guide, the text is delivered to the programmers who create the file.
