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