Season of Docs: Preparing to write

Season of Docs prep

In the last post, I mentioned my new role as a technical writer in the Season of Docs program. In the month since Google announced the results, we were in the community bonding 1This is when technical writers get to know their mentors and the open source organization, and iron out the project details. phase of the project, during which time my mentors have been introducing me to the relevant team and setting expectations.

I found out right away that the platform was undergoing a launch with new features, and so the proposal I had originally submitted with my application was already outdated. I had a couple of weeks where I scrambled to learn and test out the new features and rewrite my proposal. So far so good.

Then my mentors gave me two tasks:

1. Figure out how a typical user would access the docs, and
2. Decide on a hosting platform for the docs.

Um what? I’m just here to take directions, I said.

I jest, I never said that. (I just thought it.) So anyway, that’s how I learned about hallway user testing and publishing platforms.

What is Hallway Usability Testing?

If you’re thinking ‘stand in a hallway and test users?’, you’re not far off. Typically, it’s done by positioning yourself in a high-traffic area, and annoying asking random passersby to stop and test your product (as opposed to choosing people based on certain skills). The feedback is useful for revealing any issues with the product’s design, usability and so on.

Thankfully we live in the age of the Internet, so I didn’t have to stand in a hallway like a loser and try and talk to people (introvert’s nightmare!). The goal was to figure out where someone would expect to find help (the docs) as they were working on the platform. This would help us decide where to place links on the site that would lead to the documentation.

So I took some screenshots and annoyed emailed some friends asking them to pretend they were using the platform and needed help. I asked questions like

• Where would you expect to find help?
• What are you looking for? (A Help menu? A demo?)
• Would you expect to find the information you need on the same page or elsewhere?

I was going for an exhaustive analysis so I asked a grand total of 6 people for their opinions. I’m not Gallup Poll, what do you want? Anyhow, their answers were pretty consistent which is good enough to go on.

Hosting platforms for documentation

For what shall it profit a man if he shall write fantastic docs but no one reads it?

The Book of Geeks

Next, I had to research a platform for hosting the docs. The only caveat was that it had to be possible to download or export content in case the hosting website went bust.

I came across these:

Docusaurus: This came up high on the search results for hosting open source documentation, but a few minutes of reading told me I had to install weird things like Yarn and Node, and use the command line for practically everything which freaked me out enough I ran away screaming like a banshee. I’m sure this would work for a braver person, but I will never know.

Github Pages: This is a static site hosting service that hosts your docs directly from your Github repository. This seemed approachable enough, except that Github Pages only lets you have one free hosting service for each repo, and Oppia (the organization I’m working for) already used up their quota. So this wouldn’t work.

Break time! What’s a static site, I hear you ask? It’s a series of plain HTML files – with each file representing a page of a site. The content is fixed and the user sees what is in the code of the page. No programming knowledge required to build!

A dynamic site (like your Facebook feed page) builds webpages ‘on the fly’ using server technologies when someone visits the page. You type in a web address, the server puts together a bunch of different information in a single web page and gives you the result. The content changes with every visit and the user sees a server-side scripting language like PHP, JSP etc.

Gitbook: I heard about Gitbook from another open source organization, and I really liked the look of their theme. It provided a neat interface that I could write directly on, with no command line in sight! My only concern was whether I could export the content once published. Gitbook says you can, but then they want to delete your account as soon as that’s done… like a goddamn jilted lover.

And finally (drum roll)… the winner!

Read the Docs: This platform lets you import documentation from any version control system (like Git). You can set it up so that every time you commit code (save a change), the docs get built automatically, so the two are always in sync… like really annoying cute couples. Anyway Read the Docs is apparently the largest open source hosting site in the world, so I figured this was worth looking into.

Read the Docs generates documents written in Sphinx. Thus far, my only association with that word was a certain statue in Egypt:

I’ve since learned that Sphinx is a document generator used by the Python community. You use a lightweight markup language called reStructuredText (RST) or Markdown (or both!) 2There seems to be a RST vs Markdown debate online (kinda like Team Michael or Team Rafael (obviously Rafael—duh)). The impression I get is that using Markdown in Sphinx is like using a crutch since RST is specifically designed for technical documentation and is more extensive. You can read Victor’s and Eric’s thoughts on this. to write the documentation. If you’re interested in how you too can publish documentation on Read the Docs from knowing nothing like I did, stay tuned—I’ll have some tutorials up soon.

The doc development phase has now begun, aka the official start of the project. It’s been slow as I’m still wrapping my head around Sphinx and RST, but I’m finally writing!