your secret weapon: the documentation bible€¦ · • inadequate time for 1-on-1 training •...
TRANSCRIPT
![Page 1: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/1.jpg)
PRESENTED BY
Your Secret Weapon: The Documentation Bible
Kate Schneider Senior Technical Writer, MadCap Software
![Page 2: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/2.jpg)
About Me • Senior Technical Writer at MadCap • 9 years in software industry
– 6 as a technical writer – all using Flare! – 2+ years at MadCap!!!
![Page 3: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/3.jpg)
![Page 4: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/4.jpg)
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
![Page 5: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/5.jpg)
The Problem • No instruction from previous writer • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end
![Page 6: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/6.jpg)
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
![Page 7: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/7.jpg)
What a Documentation Bible Is How your team writes its documentation.
• Training – Procedures – Voice – Authoring tool
• Reference – Internal procedures/how-to – Style guides
• Sandbox
![Page 8: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/8.jpg)
What a Documentation Bible is Not • Your actual Help project • Copy of a published style guide (e.g., Chicago) • Flare Help
![Page 9: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/9.jpg)
Creating the Doc Bible • Set it up like your main Help project
– Global Project Linking: conditions, styles, page layouts, snippets
![Page 10: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/10.jpg)
Example: Global Project Linking
![Page 11: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/11.jpg)
Example: Global Project Linking Create in
Project Import Editor
Add common project files
![Page 12: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/12.jpg)
Example: Global Project Linking
Select applicable
condition tags
![Page 13: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/13.jpg)
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
![Page 14: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/14.jpg)
Welcome Topic • Info about basic or important job tasks • Reminders or guidelines • Links to Read First topics
![Page 15: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/15.jpg)
Example: Welcome Topic
Read this stuff first!
Team guidelines
![Page 16: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/16.jpg)
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.
![Page 17: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/17.jpg)
Example: How-To Topic Does not rewrite
Mimic Help
Gives information
about how our team uses palettes
![Page 18: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/18.jpg)
Example: How-To Topic Topics look just like
topics in Flare’s help: conditions, drop-
downs, styles, etc.
![Page 19: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/19.jpg)
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
![Page 20: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/20.jpg)
Examples: Style Guides
How our team uses punctuation
Noting a common error
![Page 21: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/21.jpg)
Audience Participation!
![Page 22: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/22.jpg)
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
![Page 23: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/23.jpg)
Training with the Doc Bible • When most content is added • Learning workflows and procedures • Four stages
– Reading – Updating – Writing – Review
![Page 24: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/24.jpg)
Reading • Learn procedures • Ask questions! • Independent learning
![Page 25: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/25.jpg)
• Learn voice, style • Out-of-date, errors? • What can you add?
– Notes? – Screenshots? – Snippets?
Updating
![Page 26: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/26.jpg)
• Practice techniques & workflows
• Add new topics, rewrite topics that need it
• “To Do” topic
Writing
![Page 27: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/27.jpg)
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
![Page 28: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/28.jpg)
Audience Participation!
![Page 29: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/29.jpg)
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
![Page 30: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/30.jpg)
Doc Bible Best Practices DON’T… • Neglect the DB! • Try to document everything on Day One • Rewrite existing documentation
![Page 31: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/31.jpg)
• Flare template • Starter topics and
basic resources • http://assets.madworl
dconference.com/docbible.zip
• (Also, go ahead and reuse this presentation to teach new writers how to use the Doc Bible!)
Sample Doc Bible Project
![Page 32: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/32.jpg)
@MadCapSoftware @MadCapDocTeam
Thanks! Keep in Touch!
![Page 33: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/33.jpg)
PRESENTED BY
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)
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.
![Page 34: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/34.jpg)
PRESENTED BY
![Page 35: Your Secret Weapon: The Documentation Bible€¦ · • Inadequate time for 1-on-1 training • Outdated training manuals • Conflicting information • Thrown in the deep end](https://reader034.vdocuments.net/reader034/viewer/2022052101/603b3ac62a866723137f4515/html5/thumbnails/35.jpg)
Questions?