Home »

Write the Docs Newsletter – March 2019¶

Hi everyone! Beth here, with your March newsletter. How on earth is February over already?

We’ve got lots of conference news to share with you. Potential speakers, you’ll be excited to hear that the Prague Call for Proposals is open. Get working on those submissions - they need to be in by midnight (CEST) on Tuesday 30 April.

And there’s even more going on in Europe: a new conference in Vilnius, Lithuania! It’ll be two days, 2-3 June; the CFP and ticket sales are opening soon.

On the other side of the pond, Portland speakers have been announced. If you’re considering buying tickets, do it soon so you don’t miss out: they sell out earlier every year. Want to go but need to persuade someone senior that it’s worthwhile? The convince your manager page might help.

Finally, we wanted to let you know that we’ve updated our code of conduct. Some sections have been improved and others clarified - for full details, check out the code of conduct blog post.

On to what we’ve been talking about in Slack!

Roadmaps and documenting ‘future features’¶

As documentarians, we sometimes come head-to-head with other stakeholders on what to include in our documentation. One contentious topic is forward-looking statements: some stakeholders might want to tell users that a feature is coming soon. But when we mention a future feature in docs, it can be a problem if that feature doesn’t end up being delivered.

Here are some thoughts about how to approach this from a conversation about roadmaps in documentation this month:

Be aware that documentation saying that something will be delivered, or even when it’ll be delivered, can be considered legally binding. You might want to consider a safe harbor statement.
If your roadmap is in the documentation, who responds to feedback on that roadmap? The doc writer may not be the best person.
Documentation is likely not the appropriate place to store a roadmap. Product managers should instead consider customer support sites or other publications from the company. Publicizing the roadmap is gaining traction (here’s an article about the idea).
If the roadmap or future features must exist somewhere in your documentation, release notes can be a good place for them. But consider creating a separate document instead that can be shared with customers - with all of the appropriate disclaimers.

Do you have opinions or advice on this? Head on over to #general!

Objectives and key results (OKRs) for documentation¶

Though it can be difficult to identify measurable data for documentation, it’s common to be asked for OKRs nevertheless. (If you’re new to OKRs or need a refresher, check out this re:Work guide: Set goals with OKRs.)

Whether your manager asks for them, you’re craving some structure for your docs planning, or you just want to have the information on hand, how do you figure out what to measure? When this topic came up this month, the WTD Slack community had plenty of suggestions:

Separate the objective from how you will measure it. For example, if your objective is to improve your documentation coverage, the measurable OKR might be that you will add 4 high-value workflows or tutorials into docs.
Use Google Analytics on your docs site to track things like usage trends, or add ratings or feedback functionality to your docs. The information you gather can help you identify OKRs that will have the most impact for your users.
Base OKRs on your goals for the docs. For example, reducing the number of questions that Customer Support handles.
If you aren’t as concerned about measurability, think about OKRs in terms of answering the questions “Where are we going?” (the objective) and “Are we there yet?” (the key result).

The whys and wherefores of cover letters¶

A question about how detailed a cover letter should be, posted in the ever-popular #career-advice channel, produced a lively discussion. While it started with what you should put in a cover letter, it expanded to the purposes of a cover letter, when or whether to include one, and more.

Some folks expressed aversion to cover letters, especially if they’re required as part of a longer, more detailed application process: they’re a lot of work, and it’s not always clear that anyone reads them. But others - hiring managers in particular - really appreciated them.

In general, people seemed to agree that it’s a good idea to write at least a brief cover letter that focuses on the job posting and shows how your skills, background, and interests are relevant. But as always - it depends! Do you have a connection or a referral, or some other personal or specific relationship to the job you’re applying for? Then a “warm intro” that shows you know something about the job and the company is pretty straightforward. On the other hand, a “cold intro” where you have no particular knowledge or insight might make a cover letter seem all the more useful - but also much harder to tailor to the specific job.

It was also pointed out that a cover letter can be a great way to explain your sideways, unexpected, or less-than-conventional entry into the position you’re applying for - often the case for docs-related jobs.

Moving to docs-as-code: static site generators¶

It’s no secret that many of us are keen on the docs-as-code approach. But as someone asked this month: if you’re moving from a traditional authoring tool like Flare, and want to start storing docs in Git, what should you use to create the docs themselves?

Static site generators are a sensible answer. But how to choose one? There are so many! The community had a few suggestions to help out, including to check out O’Reilly’s free intro to SSGs, or these introductions to Jekyll, Hugo and Sphinx. There were also few specific recommendations: