When we started development on Vendr, we knew that we were going to need great documentation as no matter how simple we aimed to make our API, the reality is, eCommerce is complicated and so nobody was going to be able to just "figure it out". But we also knew it wasn't just about the core Vendr documentation. From our experience with Tea Commerce we knew the core product was just the beginning. Along side this there were numerous add-on features we planned to release and an whole host of plugable payment providers which we wanted to ensure were all fully documented as well. 

We knew then that documentation had to be a first class citizen and that it wasn't something that we would be able to just throw together. We needed to have a plan and an architecture in mind.

The Structure

As we started to think about the structure of our documentation, we did a lot of research online reviewing products that we revered for their excellent documentation such as Stripe and VueJS and asked others what their favourite documentation was too.

We found lots of great examples, and at the same time came across an excellent article (now converted into a microsite about the documentation approach) by DIVIO a web platform provider that detailed what makes great documentation. In reviewing the article, we found that many of the great examples of documentation we found followed a similar structure and so it all made perfect sense to base our documentation on this strategy.

Ultimately, documentation can be broken down into 4 key areas (though we added a fifth for key 'Getting Started' info) with each area being focused on a specific type of user:

1. Tutorials - For people interesting in learning how to use the product but at this stage don't need to know all the different options. Tutorials should show an approach to achieving a set goal which users can follow to achieve the same goal.
2. How-to-Guides - For people who have a specific problem to solve. How-to-guides provide step by step instructions on how to solve the particular problem.
3. Key Concepts - For people looking for understanding of a topic, the key concepts section explains the theory and thinking behind the different concepts that the system is made up of. 
4. Reference - For people seeking specific information about a specific API, the reference docs provide direct information about the API and it's accepted inputs / outputs. It is expected that people reading the reference docs already have an understanding of the relevant concepts.

By breaking the documentation up in this way, it meant that each area had a clear focus on a particular user and their expected knowledge and so you could avoid over complicating the tutorials / getting started guides as those are not the time nor place to explain those concepts. 

It also meant that within the key concepts areas, we didn't have to provide step by step examples of every little thing, rather we could just focus on getting the details of the concept over.

All in all the structure worked great and as we embraced the areas, it made deciding what to add and what to remove so much easier.

The Implementation

Once we had the structure for the documentation, the next big hurdle was how to actually implement them. One key thing we knew we wanted was for the documentation to be completely open source in order to allow community contributions should anyone find an issue in them. This then meant that if anyone did want to make a contribution, it had to follow a similar contribution process they would already be familiar with. And lastly, we wanted to automate deployments as much as possible.

In the end then our solution was to use markdown for the main content of the docs and use a static site generator to do the building. As we at Outfield Digital are big fans of Vue JS we decided to use a static site generator called Gridsome. In order to make the documentation open source and easily contributable we decided to host the docs files on GitHub meaning developers could contribute by creating PR's like they would when contributing to other code projects.

The final piece of the puzzle was automating the deployment which we solved by using a great service called Netlify. With Netlify we were able to quickly setup a build process linked to our GitHub repository that automatically builds the Gridsome site and deploys it onto the Netlify CDN.

Conclusion

The biggest conclusion we came to is that documentation is hard! Writing great documentation that answers every possible issue that a user might have is really a never-ending task. But, by having a logical structure with defined user scopes and a build process that makes pushing out updates as simple as pushing a button, it puts you in a much better position to achieve that greatness.