Organizational Structure Running A Successful Business
How to write_well_(enough)
1. How to Write Well (Enough) to
Keep Your Projects on Track
Kim Chmielewicz
Rochester Chapter
2. Why discuss project
documentation?
4/17/2014 2How To Write Well (Enough)
Very often, technical writers’ unique perspectives and overview
of details = effective business analysis (many of us eventually
become project managers, whether PMI-certified or not)
Appropriate business analysis drives successful project
management, as does summation of trends, the ability to pull
together knowledge from many different sources, and the
expression of complex ideas in easy-to-understand terms (hmm,
sounds a lot like technical communication!)
The marketing flair inherent in making a compelling argument is
also helpful when it comes to promoting projects, too!
3. Project management parallels
content management
4/17/2014 3How To Write Well (Enough)
Content management = a methodology of organizing documents
by topical areas, rather than by creating static books or manuals
Recombination of appropriate topics creates documents that are
geared to different audiences (e.g., technicians and end users)
Revision and editing only requires changing one instance within a
topic in a content management system, thus making it much
easier to focus on keeping content current rather than changing
many references to a topic in different formats
The ideal way to create, compile, and maintain project
documentation for the part-time manager is to utilize a content
management approach; think of documents as information
segments that can be repackaged for various needs
4. Editorial considerations
4/17/2014 4How To Write Well (Enough)
Most project management documents are internal, so formal
syntax is not required
Create concise reports of events by summarizing one event per
line (more on this later), instead of one document per event
Write for your audience, who are probably juggling multiple
responsibilities like you do and just need to know essentials
The project manager should oversee the initial charter/plan, but
solicit input from other team members (set up simple templates)
Most project documentation can be saved to a central location
(such as a wiki) and updated by project participants as needed
Project management software should be set up to be as simple as
possible; spend extra time when setting up terminology/tasks
5. 8 documents to
(selectively) utilize
4/17/2014 5How To Write Well (Enough)
1. Project charters
2. Project plans
3. Goal logs
4. Approval/dependency tree
5. Risk logs
6. Issue logs
7. Action/agreement logs
8. Progress reports
6. 5 Steps: Project Development
4/17/2014 6How To Write Well (Enough)
1. Project Charter: goals, scope, sponsors/stakeholders, schedule
2. Requirements: specific technical requirements, test for success
3. Schedule: task sequence and dependencies, resource allotment
4. Maintenance Plan: transfer from creation to operation
5. Lessons Learned: good points, improvements, surprises
Note how the names of all 5 steps conveniently reference
documents, thereby proving that documentation is crucial for
project management success!
My suggestions reframe the 5 steps to give you ideas for adapting
your documentation plan to your particular circumstances or needs
7. Project Charter
4/17/2014 7How To Write Well (Enough)
IDEAL: Completely develop the problem statement and business
case that inform project goals to create a solid foundation for
both your project and your documentation
With such a base, your goals will demonstrate the ultimate value
of your project clearly, keeping your scope manageable and hence
increasing the likelihood that your project finishes on schedule
and that your management acumen is appreciated!
Without demonstrable value, it is very difficult to gain project
momentum
Research, write, and revise to be both clear and compelling
8. Project Plan
4/17/2014 8How To Write Well (Enough)
IDEAL: Plans may be integrated with the charter or stand alone
Include the scope, tasks to be completed, the team members who
will complete those tasks, and relevant cost/time assessments
that will be integrated into existing work schedules to complete
your project
Again, as with the project charter, gather as much information
and detail as possible to make your plan realistic, including
conducting interviews with team members, checking with any
outside contractors who may be involved, etc.
Try to be as accurate as you can be!
9. Goal Log
4/17/2014 9How To Write Well (Enough)
IDEAL: Goal separation from the project to simplify review
Create specific goals to permit a good understanding of solutions
that are being addressed by the current project
Additionally, a separate goal log makes goals more visible to team
members completing project tasks
For each goal, translate abstract wishes into specific actions,
which may then be broken down into even smaller tasks
Effective goal setting will enhance your ability to create a
realistic project plan, too!
10. Approval/Dependency Tree
4/17/2014 10How To Write Well (Enough)
IDEAL: If many signoffs are required to initiate action, the approval
tree is a helpful tool for reminding team members about their
obligations to review/refine projects tasks and actions on a
regular basis
A dependency tree may also ease the transition from project
completion to operations by tracking tasks that can be
streamlined and completed simultaneously
Therefore, by tracking approvals and dependencies separately,
you will increase the relevancy of project work by identifying
places where there are lags during your project, which may
simplify developing processes that deliver products/services
11. Risk Log
4/17/2014 11How To Write Well (Enough)
IDEAL: List any possible roadblocks to progress that exist and
anticipated solutions
Also note the impact on your project if the listed risks should
occur
The risks may be listed as part of project requirements, similar to
goals being integrated into a project charter, but a separate
listing makes for quicker reference and faster updates
A line per risk with the three variables
(roadblocks/solutions/impacts) is sufficient; remember, one line
per event, not one document per event!
12. 4/17/2014 Kim Chmielewicz 12
Risk Log Sample: SGML to HTML manual conversion
Project Stage Risk Name Description Potential
impact
Projected
solution(s)
Initial manual
review
Outdated
graphics
Component
parts updated
by supplier
Inaccurate
illustrations
may mislead
techs
Check IPL for
reworked
components
Word to
SGML
conversion
Misaligned
tables
Tables have
dangling
misaligned
cells
Tables may
require
retagging
Edit tag code
in TextEdit to
adjust prior to
conversion
SGML to
HTML
conversion
Missing
symbols
Symbols
absent or
replaced
Ranges of
instruments
may be
misread
Retag
symbols using
EpicEditor
menu guide
HTML
delivery
Garbled file Missing
sections or
out of order
Manual is
unreadable
Test view files
in different
browsers
NOTE: This risk log was composed following an initial test assessment of the
conversion process. Other risks were added as work progressed and other
potential issues came to light.
13. Action/Agreement Logs
4/17/2014 13How To Write Well (Enough)
IDEAL: Action/agreement logs are less complex and more
streamlined solutions to use instead of project minutes
The logs create a single reference point and can be referred to
easily, and contradictions highlighted, as project work proceeds
Action logs can be very helpful to use for projects in which many
small, simultaneous tasks must be completed and tracked
Agreement logs also assist in keeping track of agreed-upon
solutions
List dates, a simple description of the action or agreement, and
who participated in the discussion
14. 4/17/2014 Kim Chmielewicz 14
Action Log Sample: SGML to HTML manual conversion
Project Stage Action Name Description Actors Action(s)
taken
Initial manual
review
Brief initial
review
Quick check
to update
components,
edit, clarify
Kim
Jan
Resaved
source files
Created new
graphics
Word to
SGML
conversion
Realign tables Tables have
dangling
misaligned
cells
Kim
Betty
Retagged
tables
Edited DTD
script
SGML to
HTML
conversion
Post-
conversion
review
Recheck
HTML file
against Word
file
Kim
Sharon
Distributed
latest copies
Marked new
edits
HTML
delivery
File delivery Submit file to
online library
for use
Kim Set chapters,
zipped files,
downloaded
NOTE: This action log reflects a set procedure for manual conversion, so dates
could be added to reflect when work is actually completed for each manual
within this project. Listings with dates can be added in for unplanned steps as
they are completed.
15. Progress Report
4/17/2014 15How To Write Well (Enough)
IDEAL: To create a progress document, incorporate relevant
aspects of risk, action, and agreement logs instead of maintaining
a separate report
Maintaining the three logs as separate documents may make it
easier to record specific entries more quickly rather than
wrestling with the somewhat abstract concept of “progress” when
writing a report
If necessary, you can further illustrate progress by incorporating
an assessment of overall project status and milestone progression
in addition to the listings extracted from the risk, action, and
agreement logs
16. The “6th Step”:
Document Analysis
4/17/2014 16How To Write Well (Enough)
IDEAL: Document analysis should support two main goals:
1. A smooth transition from project tasks to operations; and
2. A realistic assessment of how well the project was planned and
executed
Look for trends in issues that came up and how closely they
correlated to anticipated risks
If issues and risks are not a corresponding set, check the
actions/agreements taken to see how they may have headed off
certain problems or created unanticipated issues during the
project process
17. Document Analysis - cont
4/17/2014 17How To Write Well (Enough)
Confirm how robust the original project charter and plan were,
both to see if appropriate team members were included as well
as creating doable tasks and milestones based on goals
Goals should have been closely correlated to your milestones in
order to enhance the correlation between your project tasks and
the desired end result of your project
Did waiting for approvals and prerequisites prevent team
members from completing their tasks?
Examine with the eye of an archaeologist (recreating a project
process) rather than as a forensic specialist (assessing as a means
of assigning blame) to keep morale up!
May also be included in maintenance plans or lessons learned
18. Takeaways
4/17/2014 18How To Write Well (Enough)
Essential documents should include a project charter, a project
plan, and action and agreement logs, which may both be
combined into progress reports when necessary
Extra time should be spent developing the documentation at the
start of your project both to create a clear expectation of the
work leading to completion and make content management easier
You may be able to spend only once or twice a week updating
your action and agreement logs once your project is set up
However, you may find it more natural to sit down at the end of
each day and summarize what has been done on your projects
dependent on what is completed each day – it’s up to you!
Logs permit quick entries without wrestling with format
19. Takeaways - cont
4/17/2014 19How To Write Well (Enough)
Simple Word documents and Excel spreadsheets work just fine for
logging purposes
Take time to consider what information is most relevant to you
and to your team/organization to record when setting up your
project documentation
Keeping regular records in a consistent manner that is natural for
you will be key to your project management success
Think of creating documentation as an opportunity for you and
your team members to market yourselves by highlighting the
value your project work brings to your organization!
20. References
4/17/2014 20How To Write Well (Enough)
My email is Mhcmik@aim.com if you have additional questions on
this presentation or about how to create documentation
For more information on content management, I recommend
taking a look at the website for the Society for Technical
Communication at www.stc.org. Much of the content is open for
viewing by non-members, and includes seminar recordings as well
as interesting articles – check it out!
Thank you for your attention – hopefully I’ve given you some
ideas for how to develop more manageable project
documentation. Happy writing!