Making a Business Case for Documentation

A presentation for the World Food Programme

​

August 1, 2024

​

​

Agenda

• Our understanding of docs at WFP
• Good documentation: Why and how
• Common pitfalls
• About the Good Docs Project
• Business case for docs
• Responding to objections
• Conclusion

2

Our understanding of the WFP context

• WFP’s knowledge base: Capturing lessons and evidence from WFP’s work and making it available to internal stakeholders globally
• Various tools for knowledge management, e.g., SharePoint and Drupal
• Documents difficult to locate — searchability is a big issue
• Need to implement processes to optimize how documents are
• Created
• Stored
• Located
• Used

3

Why?

4

In a knowledge economy,

effectiveness depends upon

transferring ideas between people

5

Think of communication channels like pipes

6

Technical communication is the art of optimizing these pipes

7

How?

8

Know your audience

Provide just enough info,

when it is needed,

to support a specific action,

at the quality required.

​

9

Learn Critical User Journeys through the information.

Create a friction log. Address friction points.

10

Audit content

• Identify communication channels
• Prioritize

11

Content types

12

Each content type places differing importance on each quality metric

​

​

​

​

Optimize

• Apply templates

13

Establish a maintenance strategy

Docs are technical debt which need updating

14

Apply “design patterns for docs”

​

• Provide organization wide consistency and quality
• Increase information density

​

15

What does good look like?

• Correct
• Current (maintained)
• Concise
• Clear (Targeted to audience and business)
• Consistent
• Complete
• Compelling
• Findable

16

Image: Pixelbay no attribution license

How?

17

With support, engineers write good docs

Kickoff

1. Discuss goals and strategy

Write

• Tech writers provide framework
• Engineers write to templates
• Tech writers review and polish

18

Coach and teach

Help you write better, faster

​

​

Google’s tech writer training

• https://developers.google.com/tech-writing

​

19

Common Pitfalls

20

Common areas picked up by tech writers

• Disjointed messaging, from
• Organization silos
• Content
• Information overload
• Structure
• Ambiguity
• Maintenance strategy

​

21

Doc quality reflects process ^ quality

and product

• Multiple points of truth in requirements
• Reflects system architecture maturity

​

• Inconsistent messaging
• Reflects siloed teams

22

About The Good Docs Project

23

The Good Docs Project

• A global community of technical writers, doc tools experts, software engineers, and UX designers
• Committed to improving the quality of documentation in open source software and beyond
• Creating and publishing templates for documentation on our website

​

24

​

​

​

25

About me

• Based in Chennai, India
• Contractor for an international development organization based in the U.K.
• Maintain online courses that reach a global audience of researchers
• Traveled widely to facilitate capacity building workshops
• Contributor in the Moodle open source community
• Joined The Good Docs Project in 2023

26

Business Case for Docs

27

Background for this talk

• A work-in-progress tactical article
• Authored by Lana Novikova and Ravi Murugesan

​

​

​

28

Good documentation in any organization can…

• Help people create, store, locate, and use knowledge easily
• Empower stakeholders to find answers on their own
• Mitigate loss of key knowledge held by staff members
• Foster collaboration
• Reduce onboarding time and costs
• Help to fulfil legal obligations
• Facilitate remote-work efficiency

​

29

Good documentation does not emerge organically

• Often, what emerges organically is lots of uneven documentation
• Starting point for good documentation is intent
• Must convince management to make that intent a reality
• How to make a business case for documentation?

​

30

Elements of a one-page business case for documentation

• Summary of the business case, clarifying the type of documentation
• Why good documentation is needed — with evidence
• Top issues or pain points — with evidence
• Approach you recommend
• Expected results from the approach
• Cost estimates
• Measuring return on investment — talk metrics!

​

​

31

Focus on business impact in the business case

Examples of business impact of good docs:

• Improving revenue, funding, or reputation
• Saving costs
• Mitigating risks

32

Business impact: Improving revenue, funding, or reputation

• Developing proposals and reports with a solid evidence base
• Appearing trustworthy and reliable
• Accumulating organic traffic to the website

33

Business impact: Saving costs

• Reducing support load and response time
• Empower stakeholders to find information
• Reduce onboarding costs

34

Business impact: Mitigating risks

• Prevent knowledge loss
• Reduce barriers to collaboration
• Fulfill legal obligations

35

Bring your perspective to the business case

• Assess the current state of documentation
• Reflect on the causes for documentation challenges
• Consider the problem from a business perspective
• Think of solutions to overcome the challenges
• Articulate the business case

​

36

Determine return-on-investment of documentation

• List tangible and intangible benefits of good documentation
• Choose relevant key performance indicators (KPIs)
• Measure your cost factors
• Quantify and monetize the benefits

​

37

Responding to Objections

38

Think of objections, and prepare to respond

• “Documentation is in bad shape? Since when? Whose fault is it?”
• “We have bigger priorities to attend to.”
• “Can we just do some quick fixes to improve the documentation?”
• “We have no funds for new projects.”
• “Documentation will anyway become messy sooner or later.”
• “Can we use AI to improve documentation quickly and cheaply?”

​

39

“Documentation is bad? Why?”

• Be wary of retrospective analysis overshadowing the business case
• Probably no single person’s fault that documentation is messy
• Recall: Good documentation doesn’t emerge organically

40

“Have bigger priorities, sorry.”

• Bigger or other priorities will always be there
• Make a case for how good documentation is aligned with those priorities
• Greater efficiency, productivity, joy, etc.

​

41

“Can we do some quick fixes?”

• Organization docs are likely vast
• Improving docs is not a matter of find-and-replace
• But shouldn’t come across as a prolonged effort
• Explain how your approach is optimized and efficient

42

“No funds, sorry.”

• A very likely objection, especially in a nonprofit
• Improving docs shouldn’t be a now-or-never thing
• Present a business case for the next fiscal year
• Think of how to persuade the funder that documentation is critical

43

“Won’t documentation relapse into a mess?”

• Project management: Improving the docs
• Change management: Making the improvements stick

44

“Can AI fix it?”

• AI not a magic wand
• Generative AI can be useful for some tasks
• Explore which tools might be useful
• Investigate costs, benefits, and risks of using AI tools

45

Conclusion

46

Is this all of us?

47

• Q&A time
• Short feedback survey: https://bit.ly/good-docs-feedback-wfp
• We’ll get in touch once our business case article is published
• Link to this presentation: https://bit.ly/good-docs-slides-wfp

​

Ravi Murugesan, sysmulch@gmail.com�Training specialist in international development

Cameron Shorter, cameron.shorter@gmail.com�Ex Google Tech Writer, Business Analyst, Engineer

48