Announcing Grok the Docs

Are my docs working?
Are folks getting what they need?

I’ve asked myself these questions a lot. Historically I have put Google Analytics on my doc pages, and called it good. I would browse over the data every once in a while, gleaning basically zero information out of it.

Read the Docs hosts a lot of documentation, and I want to help these folks understand how their docs are being used. So I have been working on a project for the last month called Grok the Docs.

Grok the Docs is a bit different, with the main difference being it embeds the information in the page for you. This is interesting because it adds context to the data. I believe that context is the first step from turning data into information. The main interface to Grok the Docs are keyboard shortcuts within the documentation page. So you can access information about the current page you’re on, while you’re browsing. Check out the Example below to see it in action.

Surfacing analytic data in the page is great for the maintainer and user alike. The maintainer can see what parts of their docs are being heavily used, and which parts aren’t being used as much. Users can see where other people are ending up, which is probably where they want to go too.

This is very much just a tech demo currently. I would love feedback from folks about how I could improve the display of the data. Currently it’s something that you need to enable.

It would be great if you have ideas for other additoinal functionality that could be added. This is very much an experiment currently, so I’d love to hear any thoughts you have. Please email or tweet me if you have feedback or ideas.

Once the code is more baked and solid, the plan is to turn it on for all Read the Docs users. After I do a full rollout across Read the Docs, I’ll consider opening it to other people. The code is currently closed source, and will likely remain so. The idea is that this might become a product that can suppliment my Gittip income. If it fails as a product, I will then open source it. That said, it will always be free for documentation on Read the Docs.

This project was done as part of my ongoing work to improve documentation. If you think this work is important, you should support me on Gittip.


This shows how user might harness this data.

Hey there! I'm Eric and I work on communities in the world of software documentation. Feel free to email me if you have comments on this post!