We need to do a documentation inventory at work. We’ve added a lot to the docs over the past year, and we’ve got a few things lurking around in there that need to be flagged for QA or revalidation. The stock answer is “put all the pages in a spreadsheet and start clicking/scrolling and annotating the list,” but I’ve been pining to fiddle around with a tool for a little while, and spreadsheets suck, so I decided to see how quickly I could put something together to make the job a little easier for the team (and reviewers down the road).
I started out with a Padrino app, which was a great way to do a proof of concept on what I was after:
- Find all the Markdown files in the docs repo.
- Use the filenames to compose the live URLs of each document.
- Pull the HTML in from the server and store it for fast retrieval/decomposition
- Identify all the elements of interest on each page and store them with a checksum.
For that last, “elements of interest” became “ordered lists and things inside pre tags.” They represent the step-by-step instructions in the docs; either in “do this, then this, then this” form, or in “start typing this stuff on the command line” form. They’re the things people gravitate to and start following, and we know that the average technical user is prone to looking for just those things and not looking at the surrounding text.
Putting a checksum on each of them will provide a way to do reports that show when an element appears on multiple pages, and across multiple versions of the docs. You kind of expect things like ordered lists to change a little over time. If one has persisted over four or five releases without changing, you might want to look at it and make sure it hasn’t been overlooked.
So after four or so hours of work, my Padrino app could do all that stuff, wrapped up in Bootstrap.
I could fire up the app, get a list of all the documentation pages by product version, and use some widgets to do a few useful things:
- See all the elements of interest in their own tab.
- Preview a docs page, then click a button to show only the headings, pre blocks, and ordered lists.
That seemed pretty useful just as a way to help someone rip through a collection of pages and look for just the things most likely to cause a user pain, then maybe enter them in a log.
Once I was home for the weekend, though, I realized that I wasn’t as familiar with Padrino as I once had been with Rails, so I decided to do a quick port. Since I’d used ActiveRecord for the original app, and since I was happy with my db schema, it was pretty simple to set up the models, re-run the migrations, and reuse the importer scripts to repopulate my development db with content.
I spent a few hours on Saturday and a big chunk of Sunday trying to see how far I could get before, well, having enough time to blog about it before ending the long weekend and going to bed. I didn’t want to put any more time in on it at work, because if I ran into a dead end and couldn’t make what I wanted, I didn’t want to feel obligated to try using it.
I had to relearn a few things about Rails that have changed since I last used it much (during v2 times), and I had to learn some new things about jQuery that I’ve never dealt with before. Still, I’m pretty happy with where it’s at now:
First, I implemented flags. For now, all you can do is flag a page if you see something you think might be a problem that needs further review. I’ve got a few ideas about how to flag individual elements. One way is super simple, but doesn’t allow you to flag them in the context of the text. The other is tougher and I’m still working on relearning Rails’ AJAXy stuff to figure out a way to flag an element in place, store it, then have it highlighted as flagged next time you visit that page.
Next, I added a working user authentication model with Devise, so flags can belong to individual people. For now, it just means that if two people look at the same page, they don’t have to agree on its flaggability. Down the road, it’ll mean there’s a way to share the tool with all our technical reviewers so that they can flag things and we can capture all the flag data from them. I’d like to add a way to enter a comment, too, but one thing at a time.
Finally, I got thiiiiis close to making the flag button truly dynamic. All the AJAX stuff I knew from when I built my last Rails app has changed, and I couldn’t figure it all out in time, so for now I just force a page refresh when the user clicks the flag button to get it to change its state from “flag this” to “unflag this.”
There are a few more things I’d like to get to:
- Report pages, naturally: Every flagged page, how many flags it has. That won’t take much.
- Flaggable elements (ol, pre): I can already do this the easy way, but I’d love to do it the hard way.
- Comments to go with flags, with design to accommodate a running list of flag comments down the side of a page preview.
- Dynamic page import. Right now, we get the map of all the files then suck in their HTML and store it. The advantage is that it’s pretty fast. The disadvantage is that the content will drift from reality over the course of a release cycle. Way better to either suck it in each time the page is viewed or offer a “re-import the HTML” button people can hit.
- Links straight to the files in the Github repo, so people can quickly fix things from the app if they spot something.
It’s in a place where I knock most of that stuff off with another leisure-time sprint, then see about hosting it somewhere relatively secure where I can put it in front of a few people for real feedback.
It also reminds me of all the stuff I wish I knew more about, like testing. I guess if I can get it into a useable state for other people, I can use it as a sandbox for learning about that stuff.
Anyhow, here it is. Hope you had a good Presidents Day weekend. Good night.