Choosing the right tool for Documentation
📋

Choosing the right tool for Documentation

Recently, we’ve been trying to improve the Product Practice at Media.net. It’s been a fun challenge that has us formalize a lot of things we did, as PMs, in an individual capacity while trying to ensure that the flexibility that enables us to be innovative is not curtailed. One of my last posts was about the combined roadmapping exercise we just undertook, which you can read about here. The new problem we are trying to solve is that of documenting. It’s a tough cookie to crack.

What do I mean by documentation?

Documentation is weird becuase if you’re familiar with the agile manifesto, you know that one of the four tenets is - Working software over comprehensive documentation. So, by that logic, time spent by a PM documenting stuff is time that could have been spent building stuff and you should try to minimize it as much as possible. This sounds great, but as any PM with a few months of experience would know, not documenting stuff has you answer the same questions over and over again. At-least, this is in my experience. So you need basic user documentation. One more thing that a lot of PMs can relate with is if they manage a complex product, features get lost easily. Look at MS Word or Photoshop - I’m sure not even the PMs working on the product know all the features of the software. Now my product is not on the scale of Word or PS, but it is complex enough. Years of feature creep and multitude of stakeholders mean that underutilized features often get forgotten. So you need some kind of a document where you can keep a track of all your releases, aka release notes, which can be easily looked up for specific functionality. One last thing that you need is a release email informing everyone of the new functionality, this is specially true for internal products as there is no AppStore where people will see the updates listed out or ad campaigns letting the people know about new features. A lot of internal products don’t have an announcement center to inform people of the new stuff too.

So basically for me the minimum documentation a product needs has 3 components-

  1. Release Email
  2. Release Notes
  3. User Documentation

What do I need in a documentation tool?

  1. Automate grunt work: Writing documentation is no fun for me. Writing about things that are already done and in a pedantic way just doesn’t get me excited. Also I hate formatting, remembering the post at a certain time and choosing the audience for it. All of this should be set up and automated.
  2. Single web-page for release notes: The tool should create a webpage, on a custom domain, that lists out all the releases in chronological order with a brief summary, relevant tags and link to more detailed documentation. It was very important to me that the tool provided a quick-glance top level view that helped people stay up-to date.
  3. Detailed Feature Documentation: Each feature should get its own page with some formatting options (like Notion) and ability to save templates. Ability to collect feedback via comments and reactions is also a good to have.
  4. Search and Filtering: The entire documentation section should be searchable and support filters at product group, product and feature levels in addition to other generic filters like date, author, tags, etc.
  5. Emails: The tool should be able to schedule emails, save email templates, provide similar formatting options to feature documentation, create custom audiences and curate replies.
  6. Analytics: The tool should be able to provide the open rates for emails, daily/monthly visitors to all pages, CTRs from release notes to feature documentation and maybe some other analytics to understand traction of the documentation.

(Don’t) Build your own (maybe)

Now, for me personally, I didn’t think building a documentation tool will be the best use of our developers’ time.

  1. This was because even if they can build it, it wouldn’t be as good as 3rd party tool that specifically handles documentation.
  2. It would also block bandwidth for other business critical projects.
  3. The cost of 3rd party options also showed us that building our own would be a costlier solution.

Notion

Notion is the new darling of the PM community. It is amazing. It is flexible in the right places, structured when you need it, it integrates with all other popular tools we use. Documenting in Notion is very attractive.

  1. It integrates with a bunch of email schedulers with its API. You can even schedule social media posts with things like Queue.so for external facing products
  2. It lets you create powerful databases that can be used to make a release tracker with all the filters and views you might need.
  3. It lets you make multiple templates that you can use for different purposes.

What it lacks?

  1. It doesn’t have analytics support.
  2. You have to integrate with 3rd party tools for scheduling stuff
  3. As a general purpose tool, webpages based on Notion (like this blog) don’t have all the specific benefits a more focused tool might have
    1. A widget to embed in your product
    2. Custom Audiences
    3. Feedback Collection
  4. If your company is a Google Docs or an MS Office company then it’s difficult to justify buying Notion at their per user cost just for documentation for most orgs.

Docsify

Docsify is another tool that is very popular amongst developers. It provides some unique advantages like-

  1. It is open-source and hence highly customizable to suit exactly to your needs.
  2. You deploy it to your own server, so you can make it as accessible or as restricted as you want.
  3. It uses Markdown for formatting, which is extremely popular and makes the content easy to customize.

What it lacks?

  1. Our current implementation of Docsify, requires one to raise a PR to update the content which is just too much friction.
  2. It needs developer time to implement, which most PMs would like to avoid.
  3. It is too flexible resulting in a high setup cost in terms of both time and money.
  4. For me, it also results in a paralysis of choice.

Conclusion: Focused Documentation Tools

I went and did a deep dive in the release notes space - creating a bunch of accounts and a mock release note section with different tools. The ones that stood out were the following-

  1. Launch Notes
  2. Olvy
  3. Beamer
  4. AnnounceKit

I also checked out Headway, RelaseNotes and a few others but it was clear they weren’t the right fit for us. After some trial and error, and talking with the support I have finalized Olvy to set up our release notes. This is because of the following reasons-

  1. Unlimited Users
  2. Custom Domain
  3. Organizing information at Product Group → Product → Feature level. So later when we add contextual because they want to join in the fun, they can just create contextual-product-feature
  4. Ability to add comments and reactions, might not need it right away but good to have
  5. A linear change log that expands into more detailed documentation - this feature is not as common and it’s really important. There should be a top level view of all the changes and a brief summary which expands into detailed documentation if clicked on.
  6. Auto Email updates (need to explore this further but certainly good to have)