Scribd
Upload
65 views

Your Secret Weapon: The Documentation Bible: Kate Schneider

The document discusses the importance and benefits of creating a "Documentation Bible" for technical writing teams. It recommends establishing a central repository in the authoring tool to serve as a training, reference, and sandbox resource. The Documentation Bible should include information like workflows, style guides, procedures, and how-tos to establish consistency and combat knowledge loss. It is not the actual published help content, but rather a reference for training new hires and updating documentation practices. Maintaining the Documentation Bible involves keeping it current and allowing new writers to contribute as part of their onboarding and training process.

Uploaded by

12345usethis
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
65 views

Your Secret Weapon: The Documentation Bible: Kate Schneider

The document discusses the importance and benefits of creating a "Documentation Bible" for technical writing teams. It recommends establishing a central repository in the authoring tool to serve as a training, reference, and sandbox resource. The Documentation Bible should include information like workflows, style guides, procedures, and how-tos to establish consistency and combat knowledge loss. It is not the actual published help content, but rather a reference for training new hires and updating documentation practices. Maintaining the Documentation Bible involves keeping it current and allowing new writers to contribute as part of their onboarding and training process.

Uploaded by

12345usethis
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 35

Your Secret Weapon:

The Documentation Bible

PRESENTED BY

Kate Schneider
Senior Technical Writer, MadCap Software
About Me
• Senior Technical Writer at MadCap
• 9 years in software industry
– 6 as a technical writer – all using Flare!
– 2+ years at MadCap!!!
What Will You Learn?
• Why do you need a Documentation Bible?
• What is (and isn’t) a Documentation Bible?
• How to create it
• How to maintain it
• How to train with it
• Best practices
The Problem
• No instruction from previous writer
• Inadequate time for 1-on-1 training
• Outdated training manuals
• Conflicting information
• Thrown in the deep end
The Solution: The Doc Bible
• Central repository kept in authoring tool
• Review, update, and add
– Information stays current
• Reference and training tool
• Establish consistent voice and workflow
• Combats knowledge loss, inadequate time,
redundant materials
What a Documentation Bible Is
How your team writes its documentation.

• Training
– Procedures
– Voice
– Authoring tool
• Reference
– Internal procedures/how-to
– Style guides
• Sandbox
What a Documentation Bible is Not
• Your actual Help project
• Copy of a published style guide (e.g., Chicago)
• Flare Help
Creating the Doc Bible
• Set it up like your main Help project
– Global Project Linking: conditions, styles, page
layouts, snippets
Example: Global Project Linking
Example: Global Project Linking
Create in
Project Import
Editor

Add common
project files
Example: Global Project Linking

Select
applicable
condition tags
Creating the Doc Bible
• Set it up like your main Help project
– Global Project Linking: conditions, styles, page
layouts, snippets
– Bind to source control
• Most important info and procedures
• Info you’d want to know on your first day
Welcome Topic
• Info about basic or important job tasks
• Reminders or guidelines
• Links to Read First topics
Example: Welcome Topic

Read this
stuff first!

Team
guidelines
How-To Topics
• Department procedures and workflows
• How does your team use:
– Authoring tool features
– Your company’s software
– Third-party tools
• Login information, websites, etc.
Example: How-To Topic
Does not rewrite
Mimic Help

Gives
information
about how our
team uses
palettes
Example: How-To Topic
Topics look just like
topics in Flare’s help:
conditions, drop-
downs, styles, etc.
Style Guides
• Internal/department style information
– Capitalization
– Product names
– Hex/RGB colors
– Deviations from your main style guide
• Terms you’re always looking up? Add them!
• Link to company/published style guides
Examples: Style Guides

How our team


uses punctuation

Noting a
common error
Audience Participation!
Maintaining the Doc Bible
• Most maintenance is done by new writers…
• Keep it current
• Add info as necessary
– Especially true for lone writers!
– Schedule time if necessary
• “To Do” topic, annotations
Training with the Doc Bible
• When most content is added
• Learning workflows and procedures
• Four stages
– Reading
– Updating
– Writing
– Review
Reading
• Learn procedures
• Ask questions!
• Independent learning
Updating
• Learn voice, style
• Out-of-date, errors?
• What can you add?
– Notes?
– Screenshots?
– Snippets?
Writing
• Practice techniques &
workflows
• Add new topics,
rewrite topics that
need it
• “To Do” topic
Review
• Typical internal review methods
– Contributor, Flare internal reviews!
– Alternative methods
• Review content, voice/tone, grammar
– Track changes
• Peer reviews, team leader
– Meet and discuss changes, questions, etc.
• Update Doc Bible if necessary
Audience Participation!
Doc Bible Best Practices
DO…
• Work exclusively in the DB
• Make the full Help project available
• Collaborate with other team members
• Let new writers ask questions and make
suggestions
Doc Bible Best Practices
DON’T…
• Neglect the DB!
• Try to document everything on Day One
• Rewrite existing documentation
Sample Doc Bible Project
• Flare template
• Starter topics and
basic resources
• http://assets.madworl
dconference.com/doc
bible.zip

• (Also, go ahead and reuse this


presentation to teach new writers
how to use the Doc Bible!)
Thanks! Keep in Touch!

@MadCapSoftware
@MadCapDocTeam
TAKE ADVANTAGE OF CERTIFIED TRAINING
As a webinar attendee, receive $100 OFF your next
advanced training course.

MadCap Flare Responsive HTML5 Training


October 18-19, 2016 (web-based)
MadCap Flare Project Management/Team Authoring Training
October 20-21, 2016 (web-based)
PRESENTED BY

For more details, click here or email [email protected]

Note: Courses subject to change. Availability based on student registration. Certain restrictions apply; cannot be combined with any other
offer or promotion. Not valid on courses already purchased.
PRESENTED BY
Questions?

You might also like