Post on 16-Jul-2015
MANAGING EFFECTIVE DOCUMENTATION
EFFECTIVELY
Sunday, July 28, 13
Customers
Engineers
New Team MembersTroubleshooting
Known Issues
Errors
Processes
Best Practices
Instructions
Implementation Guides
QA
Sunday, July 28, 13
LIFECYCLE OF EFFECTIVE DOCUMENTATION
Outline
Organize
Draft
ReviseUpdate
EditBrainstorm
Review
Sunday, July 28, 13
IMPORTANCE OF DOCUMENTATION
• Standardize processes
• Eliminate downtime by creating centralized knowledge
• Accelerate customer service with valuable instructions and guides
• Minimize the time spent researching common issues and questions
• Encourage participation among teams
• Promote effect project management
Sunday, July 28, 13
COMMON PITFALLS
• Too much time spent documenting
• Not enough time spent documenting
• No centralized “go to” locations for answers
• Readability
• Outdated, incomplete, or ineffective
• Unorganized or loosely-structured
• Low visibility, non-effective
• High price for downtime
• Vague, unclear or inaccurate instructions
• Accessibility
• Requires too much maintenance to update
Sunday, July 28, 13
TOPICS FOR DOCUMENTATION• Internal instructions and manuals
• Troubleshooting / flow charts
• Customer-facing manuals
• FAQs, forums, knowledge base
• Common questions, known issues
• Benchmark research projects
• Bugs, release information
• Reference guides
What do we need to document?
Sunday, July 28, 13
USING SOFTWARE TO LEVERAGE YOUR WORKFLOW
• Brainstorm and organize thoughts using an outliner or flow chart
• Create a bucket for new ideas, issues, questions, and requests for additional documentation
• Use a database to collaborate on ideas or initial information
• Find an application that allows the content producer to easily organize, draft, revise documents
• Create a centralized landing location for documentation ready for release
Sunday, July 28, 13
IMPORTANT THINGS TO CONSIDER
• Versioning
• Simultaneous editing
• A powerful search engine
• Chart & graph functionalities
• Customization
• Code editing & formatting
• Ability to sort by categories and add tags
• Location for feedback
• Portability & multi-platform
• Permissions
Sunday, July 28, 13
REFINE DOCUMENTATION BASED ON AUDIENCE
• Customers?
• Internal use?
• Level of expertise
• Purpose
• Readability
• Atmosphere
• Ease of access
Sunday, July 28, 13
GUIDELINES
• Updating documentation should be an ongoing process
• Reviewing documentation should occur periodically
• Ideas and needs for new documentation should be processed often
•Documentation should be integrated directly with engineering departements
• Each type of document should be standardized
Sunday, July 28, 13
WORKFLOW FOR THE CONTENT PRODUCER
Benchmark
Inbox
File
DraftRevisit
ReviseSpecialize
Categorize
Sunday, July 28, 13
FEEDBACK!
•While the documenting process is structured, the ability to pose new ideas, questions, and issues should be easy
•Quality, not quantity
• Integrate customers, staff, and other departments to actively engage in promoting better documentation
Sunday, July 28, 13