Home »

Write the Docs Newsletter – June 2019

Hello friends, it’s Beth and the newsletter team again! Summer is here and so is the June edition. It’s absolutely packed this month, so I’m going to keep this intro brief.

Portland has just wrapped up - see our first article for more on that - and Vilnius is just finishing as I write. I am super excited about Prague coming up in September, and can’t wait to see you all there; keep an eye out, as the speaker announcements should be coming in the next month or so.

Onto the articles we’ve gathered from Slack this month!

Keep riding the conference wave

Many people have been keeping the Portland conference spirit alive by posting writeups, reflections, and other resources. Here’s what we caught:

Facilitating top-notch doc review

Moving on from conference chat, there’s been plenty of great discussion recently, and one hot topic was doc review. First up: what are good tactics for educating colleagues about it and making the process more effective?

  • If your company runs lightning talks, give one! Talk about doc review, writing skills, or authoring tools.
  • Describe doc review in ways developers can relate to. Present it as the documentation equivalent of code review or link it to programming approaches like simplicity over complexity.
  • Be specific in feedback requests. Instead of asking for general reviews of entire documents - vague requests can be overwhelming - try “Can you review these 5 code samples for syntax?” or “Are the use cases accurate? Am I missing any?”
  • Thoughtfulness pays: avoid phrasing your requests as demands. Consider your words as carefully for your coworkers as you do for your readers.
  • Highlight sections that you know need the most help: “I’m not confident about this section because I had to extrapolate from incomplete information. What did I get wrong here?”
  • Welcome all feedback with enthusiasm and gratitude. Use every opportunity to emphasize that good documentation is a team effort. And let people know when their feedback is incorporated, so they know they made a difference!

As for tools and methods, it seems everyone has a different workflow!

  • Some use a Headless CMS or browser-based CMS like Paligo. Some tools have direct commenting features. Others create a Git PR from a draft, which opens up other commenting features (depending on the Git client).
  • hypothesis.is allows commenting directly on web pages.
  • Dropbox Paper is useful for drafting content and granular commenting. It also exports to Markdown for publishing in other tools.
  • Some also collect feedback using Trello cards and Jira tickets.

Running objective interviews

Our Slack community enjoyed a lively discussion on how to maintain objectivity during interviews. Objective interviewing (and interviews in general!) is a topic that lends itself to extensive discussion, strong opinions, and many different perspectives.

There’s much more to unpack about this topic than we can cover in just one newsletter article, so here are some of this month’s tips:

  • Recognize that interview methods are flawed and rife with bias, and work to do better.
  • The number of managers on a hiring panel matters less than the diversity of those managers, but both may help lessen bias on the panel.
  • If you can, consider introducing (as far as possible) a “blinded” interview process.
  • Consider training on how to be more aware of your biases.
  • Ask the questions you want the answers to.
  • Consider the subtext of questions that you do ask.
  • Exercise-based interviews can provide more relevant interactions with candidates than resumes and curated writing samples.

Documentarians recommended some reading related to this topic:

Continue the discussion in #managing-writers or #career-advice!

Order from chaos, or, a conversation about docs cleanup

Over the years, how to organize your docs been a really popular topic at Write the Docs conferences. One notable piece of advice was to seek out and make public the often-hidden or kept-private stashes of information that individuals in a company invariably gather. If it’s a problem you’re interested in, there’s an embarrassment of riches for you in the video archives:

DITA vs docs-as-code

Our final discussion this month comes from a community question about what the differences are between docs-as-code and DITA. The short answer is that docs-as-code is a practice, whereas DITA is a tool and a format. So in theory, you could practise docs-as-code with DITA just as you would with markdown.

However, it’s not necessarily that straightforward. One issue is that if you chose to use DITA, you put a higher barrier to entry on non-tech-writer contributions: reading the XML is tricky, and licenses for tools can be expensive. You can help others review by publishing the content to PDF, but that may not be an ideal review format.

The toolchains also generally differ. Typically, DITA uses a closed content management system and toolchain, whereas docs-as-code matches what developers use for their code.

DITA also emphasizes certain features, like content reuse, that don’t come out of the box with most docs-as-code tools. However, you can often add those features in - Tom Johnson’s blog series comparing DITA and Jekyll discusses this. He warns that with lots of customisations, you risk locking yourself into a particular toolchain - but others pointed out that it’s never “easy” to change docs systems anyway.

Some people pointed out the ideological differences. A lot of the point of DITA is the structure, allowing sophisticated content reuse. Docs-as-code/markdown/SSGs don’t come with the same feature set because they sometimes no have structure at all, even to the point of being anti-structure.

So while you can potentially unite the two, it’s worth remembering that the philosophies underlying docs-as-code and DITA are quite different.

Job posts

Technical Writer - Software Engineering
Google, Sunnyvale and elsewhere, full-time
Contract Writer
Airtable, SF / remote, short-term contract
Technical Writer
Lullabot, remote, short-term contract
Technical Writer
Bloomberg, New York, full-time
Senior Technical Writer
GitLab, Remote, full-time

To apply for these jobs and more, visit the Write the Docs job board.

Community events coming up

Welcome to Write the Docs Vilnius 2019!   Conference highlights and thanks to the community!