Technical writing/Project management

back to Technical Writing Level 2

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

Document Life Cycle

Document Life Cycle is a term used in Document Management Systems (DMS) , Digital Rights Management (DRM) , Document Records Management Theory , Customer Relationship Management (CRM), and Content Management Systems (CMS). The life cycle begins with the creation or receipt of the document and ends with its destruction or permanent preservation.

Writing a Technical Document

Creating an accurate and helpful technical document is a multistep process consisting of planning, drafting, revising, and testing. In most cases, a document will require contributions from a range of specialists including writers , designers, and subject matter experts. A project manager, sometimes called a Technical Writer Project Manager (TW PM) , is the person overseeing the document’s creation.

Planning

The planning stage is the period in which the writers map the path for the completed document. As such, it will vary between writer teams but normally features a timeline for submissions and a budget estimate. Additionally, the planning stage includes:

• Analyzing the expected audience for the document
• Establishing the purpose of the document
• Generating ideas for the document
• Researching information for the document
• Outlining the content of the document

Drafting

The drafting stage is the period in which the writer organizes information and ideas into sentences and paragraphs. Most technical writers will use a preformatted template at the start of the drafting process.

A technical document will normally undergo multiple drafts before approval. While some writers may still use pen and paper to draft, most will use a computer. The two most popular software tools for writing and editing are Microsoft Word and Google Docs. Other options include LibreOffice Writer, Dropbox Paper, Quip, Draft, and Hackpad.

Best practices advise giving all drafts a precise working title. The title should include keywords that describe the content. Precision in the title makes it easier for collaborators to manage the document. The working title is usually different from the final title.

Revising

The revisions stage is the period in which the writers edit the document. The process includes both line and copy edits (LINK). The first step in revising a document is always self-editing. Options for self-editing like spellcheck, grammar check, word count, and read aloud are included in word processing software.

After self-editing is finished, a writer will submit the document to other team members for feedback. The team will study the document and make suggestions for improvement. The writer will then incorporate their feedback into the draft and resubmit. The submit-critique-resubmit sequence can be lengthy but usually defers to the timeline agreed upon in the planning stage. Once the final draft is approved, the document will be sent to the publisher or the testing team (10.4).

Revising an existing, published, or live technical document normally requires less collaboration than a new document. This is because the revisions are additions, subtractions, or replacements of specific copy (e.g., a new disclaimer based on California Proposition 65) that do not alter the purpose of the document.

Testing

The testing stage is the period in which the writers learn how the intended audience responds, interacts, and uses their document. The process is called usability testing. Pilot tests, in which a single document is tested, are used to improve the reliability of the usability testing process. Properly conducted, a usability test will reveal the strengths and weaknesses of the document. The information gathered will be used to improve the document. The goal is to publish a technical document that’s helpful, informative, and intuitive.

The reason companies test documents is that effective technical documents save money. They reduce customer questions (phone, email, in-person). They reduce complaints and bad reviews. They reduce churn and product abandonment. Most importantly, they reduce accidents, even fatalities To collect valid data from a usability test, administrators need to stay organized. They must be attentive to participants, ready to answer questions as they arise. At the end of the test, they must debrief participants to clarify observations.

Once the team records the results for their test, they’ll send the document back to the writing team for revision. Upon final acceptance, the document will then be sent to the publisher.

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
  • .pdf
  • CD
  • webhelp
  • Others

Parallels between SDLC and Documentation Life Cycle

SDLC	Phase	Documentation Life Cycle
Idea for a new product	Initiation	Should the product be documented and how?
Feasibility study	Planning	Type of document and its 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, and readable
Ready for sale to clients	Implementation	Prepare hard copies, CD-ROM, online, and delivery
Support and upgrades	Maintenance	Updates, archives, and 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 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 easily 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

• COCOMO II
• CostModeler
• KnowledgePlan

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.

• Scope creep
• Cherryleaf Documentation Plan
• Documentation and QA

back to Introduction to Technical Writing

back to Technical Writing Level 2