From the beginning, the three Wavefront founders considered docs–getting information to our users–an integral part of the Wavefront experience. Clement Pang has blogged about Wavefront on the Wavefront website and on medium.com, Dev Nag prepared excellent videos that explain how Wavefront works, and Durren Shen— also a blogger — has tirelessly helped improve our reference docs. That commitment to getting relevant and up-to-date information to Wavefront users has resulted in a quality doc that helps Wavefront developers, customer success engineers, and external users.
Simple products like apps on your phone shouldn’t require docs. But power users who want to customize a Wavefront alert target, fine-tune a query, or filter search results rely on docs.wavefront.com to help them get the job done.
In this blog, I’ll give you a short tour of some highlights of our docs, and then I’ll explain how we create them using docs-as-code processes –- and how you can help make our docs even better.
What’s Wavefront Docs?
Wavefront docs include step-by-step instructions, reference pages, videos, and more. Here’s what we offer.
Getting Started Pages
To really experience Wavefront, you have to sign up for our Self-Service Trial. But if you’re not quite ready for that, we have a few Getting Started topics that include a short Tutorial, and info on Getting Data into Wavefront.
We include illustrations and screenshots in our docs – everyone knows they’re worth 1000 words!
Videos
For those who don’t learn well from written text, the docs include a large set of videos that explain how to use Wavefront. We ask developers, systems engineers, and customer success folks to do videos so you’re really listening to the experts.
We’re expanding our video library continuously as we enhance or update the product, so bookmark the link to catch our updates!
Extensive Reference Documentation
Our extensive reference documentation includes a page for (almost) each query language function. Google analytics shows that the Query Language Quick Reference is by far the most popular page in the doc set – and we intend to keep it that way by including full syntax, relevant examples, links, and caveats on each page.
Simple Search
To find information in our docs, you can use the tag-based tiles or the Algolia-based search. Because docs.wavefront.com has been around for a while, you’ll also get results from a Google search.
Best Practices
The customer success team has helped us put together some Best Practices. We’re expanding this section as we learn more from our customers. Let us know if there’s something you’re interested in!
How We Build Our Docs
Many developers don’t like to check the docs if they’re stuck because they’ve had bad experiences. Large companies can’t always keep the docs up to date, information can be hard to find, and sometimes it shows that there wasn’t enough engineering involvement. Wavefront thinks differently – our team of technical writers (both of them) works closely with engineering, customer support, and Ops, and uses tools and processes that make collaboration easy. It’s a process that’s not uncommon for SaaS docs, and we find it works!
Docs-As-Code
Docs-as-Code, also called Docs-Like-Code, is an approach where creating the doc shares many characteristics with coding. Documentation and code use similar toolsets, for example, for version control, authoring, reviews, and more.
Writers and engineers collaborate on in-product content and some of the docs.wavefront.com content using git PRs.
Here at Wavefront, we set up our docs to use tools that engineers are familiar with. We use Markdown, a static site generator (Jekyll), and git. The tech writers have sandboxes, staging servers, and a public server for the doc set. Doc builds don’t depend on product builds, so if we make mistakes we can fix them quickly.
We like to make information available from inside the product:
- We have a collapsible Help panel with lots of links to more info.
- Our integrations have the instructions right in the Setup tab.
Scripted Content Extraction from Product
Because customers want to read about Wavefront integrations without signing up for a trial, we make the information from the Overview and Setup tabs of each integration available from the doc set. Each time we merge the integration code to master, a script updates the doc HTML files. Because the product and doc use Markdown, the script doesn’t have to do a lot, and this single-sourcing makes it easy to keep the doc set up to date.
Continuous Feedback Loop
Even excellent collaboration with engineering isn’t always enough, especially if a feature addition or change results in changes to some existing behavior. For example, when engineering restructured the SDK GitHub repositories, some links in the doc broke. Fortunately, the customer success team alerted us quickly, and we were able to fix and redeploy the doc. We also look for doc related questions on Wavefront Slack channels and change the doc when we see there’s a problem. Working on Wavefront docs is an exciting project in collaboration and continuous improvement – want to help us make the doc even better?
If you’re not a Wavefront user yet, sign up for our Free Trial. With our docs, you’ll be a power user quickly — let us know how it works!
Get Started with Wavefront Follow @WavefrontHQThe post Become a Wavefront Power User: RTFM appeared first on Wavefront by VMware.
