authoring software product guidance and documentation
DESCRIPTION
Complex products need great support. This is an introduction to the importance of guidance and the different types of content you can create to help customers understand and use your products.TRANSCRIPT
Authoring Product GuidanceQuentin [email protected]
I find your lack of guidance disturbing.
Why write guidanceHappy customersOne right way, many wrong waysYou can’t answer every question individually
Happy supportFind the answers to our customer’s issuesBetter at helping customers succeed
Happy PMsYour features get used Learn ideas for next release
You’re Joe? I read your blog! You’re so hot.
Full Bleed Photos
Pictures can set a mood orevoke emotion, making fora more memorable presentation.I love a great white paper, it
makes it easier to build stuff.
Types of Guidance
Code samplesWhite papers
Blog postsKnowledge Base Articles
Capacity Planning
Help Docs
Guidance is like a recipe, great guidance makes tasty products.
Types of GuidanceBlog Posts – good for informal content, fast publishingKnowledge base articles – short articles that highlight a problem and solutions to resolve itWhite papers – in depth technical documents covering a topic with examplesCode samples – a snippet of code and a description of how to use itHelp docs – support articles that explain product features and how to use themCapacity planning – technical articles covering limits, performance factors, and sizing of hardware to run a software product given usage and load characteristics
Some words of advice…PrioritiesGuidance for complex products is essentialDo not release a product without it
It takes time, a lot.White papers - full time job for weeksBlog posts – hours per postHelp content – dedicated writers usually required
DependenciesTime for peer reviewTime for validation of guidanceTime to publish
ProcessWhite PapersTable of contents / TopicsReviewRough draftReviewMiddle draftReviewFinal DraftReviewPublish
BlogsGenerate ideasWrite table of contentsWrite code sampleReview code sampleWrite postGet screenshotsReviewPublish
What will you be doing over the next six months?
Example White Paper6 months from start to publishing41 pages, 397 revisions (tracked changes)
Defining scope:High-level “what questions do we want to answer?”Loop in experts around the team early on
Gathering data:Working with quality assurance to define & prioritize test casesWorking with customers to learn about environments and configurationsMonitoring performance counters
Getting feedbackLots of iteration
FeedbackYou will get lots of it (it’s a bad sign if you don’t)Sometimes you’ll get contradictory feedbackYou own driving resolution/agreement
If you’re not currently the SME, you will be
ReviewsWhite PapersReview ideas for sectionsReview page by pageGet the necessary experts to attend
BlogsWrite it upGet a peer to review itFeel free to include other SMEsIf code sample, have dev and test review and test it
ConclusionWrite + review + ? + publish = look cool & profit $