Atlassian

Writing tool kit for product documentation - Connect Week Austin.

Luis Ortiz

— 3 min read
Writing tool kit for product documentation - Connect Week Austin.

One of the big things about launching an Add-on is that you need to have everything in place so the user can achieve results leveraging the platform it has installed the add-on on.

But an overlooked aspect in launching software is the documentation that goes with it, as many of us know (or at least believe), not everyone reads it. So, many product teams do not put an effort into creating compelling information for it.

It was really interesting to hear Becky Todd explaining how as an Atlassian Marketplace Vendor you can create documentation the users “actually” read.

Here is a small summary on what she talked about at Connect Week Austin 2017 at Vuka Collective in front of more than 80 developers of the Atlassian Ecosystem.

Content as a component in product development.

The first thing to get out there is that creating documentation is a very painful process, there is still no easy way to go about it. There are only just a few software companies that come to mind that create great documentation, so everyone has room to improve.

There are 3 basic processes that a well-documented product has:

  • Installation.
  • Quickstart.
  • User Guide.

Installation documents.

These are the instructions for installing and configuring an add-on, which means that they have to be very detailed and with very intuitive images that will help the user through the process of understanding how to integrate your Atlassian Add-on into their workflow.

Configuration docs will vary depending on the level of access the user has, so make sure you have detailed instructions for the IT Administrator, that way you will enable a much smoother process of getting your add-on approved for installation in the JIRA or Confluence instance or the main Bitbucket repository.

Quickstart.

These are the one-page documents, that go straight to the point and are focused on just a single use case. Which makes it easy for users to find them, so focus on the discoverability of the document and start putting the right information in front of them.

Create content that is targeted to the most active users for your Add-on, for example in our Agile Retrospectives for confluence & the Jira version we target the Scrum Master since he is the one leading a projects retrospective to avoid agile anti-patterns.

User Guide.

Content around user guides is mostly about How-To’s, which can be a daunting task since there could be multiple guides for all of the workflows surrounding your add-on. Not everything needs a guide.

Make sure you take care of the most important user personas that are involved in the decision-making process of installing your add-on. It is important that you provide value in these guides, making sure they get the expected results. User research can prove a valuable tool to understand this.

Know your different user personas.

The product team has to be mindful of who the user does, what are the goals he wants to accomplish and what internal process is the product going to be supporting. All of these components are essential to creating the supporting documents that will give the user a clear workflow of the product.

We forget that we are not the user - Becky Todd - Sr. Dev Experience Manager.

Take into account that in an Atlassian platform there will be Developers, Administrators, Designers, Product Managers and VP/C level executives. Everyone one of them has a potential use for your add-on, so be aware of the possibilities to interact with all of them.

Becky Todd touched on some very important questions you need to ask yourself when you create documentation:

  • What is the user doing when they use your add-on?
  • Who is using it? (We would add - and with whom?)
  • Why do they use it?
  • When do they use it?
  • Where do they interact with it?

She also provides us with a great description of a Writing Tool Kit for documentation, which is composed of the following 3 things every product team should have to write documentation in a consistent manner:

Instructions. Yes, that means instructions about how to write documentation, how-to setup and publish content. Step by Step and by the numbers.

Style Guides. This will have all of the branding, voice and usage of the guidelines to produce content.
Best Practices. Templates for creating the documents and checklists to publish them.

A great example of a well documented Add-on is Refined Wiki.

Trying to improve your #Agile practices? OR are you getting started with Agile? Are you in a remote team? Check out our products for Agile teams at SoftwareDevTools. We focus on making agile ceremonies more effective and easier to adopt for remote teams.

Check out our Atlassian tools:

Follow us on our networks:
Facebook: /SoftwareDevTools
YouTube:SoftwareDevTools
Twitter: @softwaredevtool
Email: hello@softwaredevtools.com
And Subscribe to our blog below!

Read more