The document discusses crowdsourcing documentation content. It defines crowdsourcing as relying on volunteers to create content. The benefits are unlocking knowledge from experts, minimizing bottlenecks, and addressing specific use cases. Challenges include unclear ownership, poor quality content, and repetition. Best practices for managing crowdsourced content include writing for users, consistency, and integrating documentation into product development. A case study shows how one company built a knowledge base using these practices.
10. #writethedocs | @beckatodd
Community of equal peers
working toward a common
outcome… with no one
participant benefiting more
than any other.
Leverages the marginal
interest of a group of people
to complete a task that
otherwise could not be
economically completed.
CROWDSOURCING OPEN SOURCING
http://www.computerworlduk.com/it-business/crowdsource-is-not-open-source-3569582/
12. Unlocks knowledge
Leverages insight from experts in different
roles
Minimizes bottlenecks
More authors means fewer roadblocks to
publishing quickly
Solves specific issues
Addresses use cases not typically
documented
Advantages
#writethedocs | @beckatodd
13. #writethedocs | @beckatodd
Distributes responsibility
Ownership is unclear and can lead to
confusion
Poorly written
Content is more difficult to understand,
poorly formatted, etc.
Quantity is not quality
Topics are repeated and old topics are not
retired or updated
Challenges
#writethedocs | @beckatodd
14. #writethedocs | @beckatodd
1% create new content
9% make edits
90% view
1% RULE
http://idratherbewriting.com/2017/03/08/crowdsourcing-docs-with-github-docs-as-code-tools-same-as-wikis/
19. #writethedocs | @beckatodd
ANNE ROCKLEY
A repeatable method of identifying
content requirements up front,
creating consistently structured
content, managing it in a definitive
source, and assembling it on
demand.
21. Instructions
How to setup and
publish docs
Style guides
Brand, voice, and
usage guidelines
Guidelines
When to write, review
checklists, templates
Writing toolkit
25. #writethedocs | @beckatodd
1
2
3
What
What are they doing when
they use it?
Who
Who is using it?
Why
Why do they use it?
THE FIVE WS
4
5
When
When do they use it?
Where
Where do they interact with it?
30. 3. Docs or it isn’t done.
#writethedocs | @beckatodd
31. Content requirements
• Describe main concepts.
• Cover the main use cases.
• Update tutorials and tasks.
• Retire old content.
Content
process
Plan
Write
Review
Test
32. Author checklist
• New features documented.
• Tutorial steps accurate.
• Code samples complete and accurate.
• Screenshots up to date.
• Spell check.
Write
Review
Test
Content
process
Plan
33. PR checklist
• Copy edit.
• Voice and tone.
• Code samples compile.
Plan
Write
Review
Test
Content
process
34. QA checklist
• Are new features documented?
• Are tutorial steps accurate?
• Are code samples complete and
accurate?
• Did you notice anything else?
Plan
Write
Review
Test
Content
process
35. Putting it together
Train
In-person training, self-
help resources
Plan
Release and feature
docs planning
Edit
Comment-based review,
copy editing
39. #writethedocs | @beckatodd
Plan
Defined requirements, information
architecture, templates, and content
processes.
Train
Developed team-specific training
materials adapted from Writing toolkit.
Build
Crowdsourced the content creation.
40. #writethedocs | @beckatodd
1
2
3
Continued growth
300 + articles published and continues to have a steady flow of up-
to-date articles.
Workflow and tooling updates
Identified additional use cases and has migrated content to a new
tool that better supports their workflows.
Cross-departmental collaboration
Developed a strong cross-departmental collaboration between
Engineering and Support.
15 MONTHS LATER: SUCCESSES & CHALLENGES
