1.
Best Practices
for
Documenting
Technical Procedures
Melanie Seibert

2.
Documenting Procedures
Hello. This is me:
★ BA & MA in English
★ 5 years as a copywriter (both print & web)
★ 3 years as a part-time freelancer/full-time mom
★ 3 years total as a tech writer (2 at cPanel)
★ Now Documentation Supervisor at cPanel
★ Interested in how content is developed, managed,
understood, and used

3.
Documenting Procedures
What about you? Are you a...
★ Technical support person?
★ Developer?
★ System Administrator?
★ Executive?
★ Something else?

4.
Documenting Procedures
If you’re here, you’re also a
content producer.

5.
Documenting Procedures
The problem

6.
Documenting Procedures
The problem
Expert
(you)

7.
Documenting Procedures
The problem
Expert Audience
(you)

8.
Documenting Procedures
The problem
information
Expert Audience
(you)

9.
Documenting Procedures
The problem
needs to get here
information
Expert Audience
(you)

10.
Documenting Procedures
Documentation!
Expert Audience
(you)

11.
Documenting Procedures
Expert Expert
(you) (you)

12.
Documenting Procedures
How?
1. Plan.
2. Write.
3. Revise.
4. Edit.
5. Publish.

13.
Documenting Procedures
1. Plan.

14.
Documenting Procedures
What do I want to say?

15.
Documenting Procedures
What do I want to say?

16.
Documenting Procedures

17.
Documenting Procedures
Who is my audience?

18.
Documenting Procedures
Who is my audience?
What do they need?

19.
Documenting Procedures
Who is my audience?
What do they know?
What do they need?

20.
Documenting Procedures
Who is my audience?
What do they know?
What do they need?
How will they be looking
for the information?

21.
Documenting Procedures

22.
Documenting Procedures
★ We usually assume people know what we
know. We almost never start at a level too
basic.
★ We usually assume they want to know
what we want to tell them.
★ Many times, what we want to tell them is
mainly about us.

23.
Documenting Procedures
So...
★ Start at the beginning.
★ Listen and learn what your audience wants
to know.
★ Make it about them, not you.

24.
Documenting Procedures

25.
Documenting Procedures
This results in:

26.
Documenting Procedures
This results in:

27.
Documenting Procedures

28.
Documenting Procedures
2. Write

29.
Documenting Procedures
2. Write badly.

30.
Documenting Procedures

31.
Documenting Procedures
Everybody knows you should do things right
the first time... right?

32.
Documenting Procedures
Everybody knows you should do things right
the first time... right?

33.
Documenting Procedures
Do things badly the first time... just don’t
leave them that way.

34.
Documenting Procedures
Why?
★ Being perfectionistic will get you “stuck.”
★ You don’t do anything wrong. Because
you don’t do anything.

35.
Documenting Procedures
In writing, anything is better than nothing. So,
write a terrible first draft.

36.
Documenting Procedures
3. Revise.

37.
Documenting Procedures
This is where it gets good.
Do not skip this step.

38.
Documenting Procedures

39.
Documenting Procedures

40.
Documenting Procedures
Create a logical flow.
★ Think like your reader.
★ Question and answer format often works
well.

41.
Documenting Procedures
Be concise.
★ Don’t waste your readers’ time.
★ Be ruthless.

42.
Documenting Procedures
“Vigorous writing is concise. A sentence
should contain no unnecessary words, a
paragraph no unnecessary sentences, for the
same reason that a drawing should have no
unnecessary lines and a machine no
unnecessary parts.”
— Strunk & White, The Elements of Style

43.
Documenting Procedures
“Get rid of half the words on the page, then
get rid of half of what’s left.”
— Steve Krug, Don’t Make Me Think

44.
Documenting Procedures
Example:

45.
Documenting Procedures
What I did:
★ Formatted it as Q&A.
★ Used headings and bullets.
★ Defined basic terms.
★ Answered the most pressing questions
first.
★ Removed unnecessary information.

46.
Documenting Procedures
Why it works:
★ It’s easier to scan.
★ It’s approachable.
★ It’s understandable.
★ It’s friendly.

47.
Documenting Procedures
Another
example:

48.
Documenting Procedures
Another
example:

49.
Documenting Procedures
Another
example:

50.
Documenting Procedures
What the writer did:
★ Used a table to format details.
★ Used bullets.
★ Used tabs to display categories of
information.

51.
Documenting Procedures
Why it works:
★ It’s easy to scan.
★ The information is organized logically.

52.
Documenting Procedures
4. Edit.

53.
Documenting Procedures
★ Have someone proof your document
before publishing.

54.
Documenting Procedures
huffingtonpost.com

55.
Documenting Procedures
huffingtonpost.com
huffingtonpost.com

56.
Documenting Procedures
huffingtonpost.com
huffingtonpost.com
typobuddy.com

57.
Documenting Procedures
★ Test it: watch someone “use” your
document and listen to their thoughts.

58.
Documenting Procedures
5. Publish.

59.
Documenting Procedures
Points to consider before publishing:
★ Who are your users?
★ Where will they look for info?
★ Do they want print? web? mobile?

60.
Documenting Procedures
You’re not done
Write Revise
Plan
Edit
Publish

61.
Documenting Procedures
You’re not done
never :)
Write Revise
Plan
Edit
Publish

62.
Documenting Procedures
Points to consider after publishing:
★ Long-term maintenance: who will do it?
★ Conventions: consider starting a style
guide.
★ Consider a site audit or inventory if you
have lots of documentation.

63.
Documenting Procedures
Resources:
★ Yahoo! Style Guide
★ Don’t Make Me Think by Steve Krug
★ Letting Go of the Words by Ginny Redish

64.
Documenting Procedures
Thanks!