Home »

Write the Docs Newsletter – December 2019

Hi everybody! It’s Beth here, with the last issue of 2019. And what a year it’s been! Four conferences (including the recently-wrapped-up Australia conference), more meetups than you can shake a stick at, and an ever-busier community on Slack. For a last dose of conference goodness this year, take a look at the videos of the talks from Australia (plus fab photos), which are now available for your enjoyment.

And there’s plenty to look forward to in 2020. If you like taking the time to think about the big picture over the holidays, we’d love the gift of your talk proposal for Portland 2020 - the CFP is open until 10th January. We’re also hoping to have another US conference next year, closer to folks on the East Coast - but this is still unconfirmed. We’ll keep you posted.

So that’s all on the news front. We’ve had another month of great conversations and insights from the Write the Docs Slack - enjoy!

Documentation feedback widgets - thumbs up or down?

Getting user feedback on your documentation can be challenging, and not just emotionally! This month, our community discussed options for asking for that feedback on our help sites.

While most felt that getting direct user feedback was ultimately more useful, often that’s not possible. Implementing a widget that asks users for star ratings or a thumbs up/thumbs down can get you somewhere - but these ratings systems have their challenges.

One community member suggested that readers may only rate docs when they’re unhappy with their experience, skewing the results to the negative. Others noted that while these can give an idea of high-level likes and dislikes, a thumbs down alone doesn’t tell you what in a doc needs improving or fixing. One idea was to have a widget where, if you give a thumbs down, you’re prompted to leave a comment. But increasing the friction for providing feedback decreases the amount of feedback you’ll receive.

There was another theory for the prevalence of negative comments. Most documentation is written intentionally without the “personal touch” , or without even a byline, that would let our audiences connect with the person behind the writing.

Here is some recommended reading:

As well as some tool suggestions:

If you want to chat more about feedback widget options, jump into #doc-tools!

Our favorite keyboard shortcuts

Nothing makes you more nostalgic for familiar keyboard shortcuts than switching operating systems! Fortunately, many Windows keyboard shortcuts work for Mac if you use Command instead of Ctrl (and vice versa). But getting comfortable takes time. To help you settle into a new OS - or just learn some handy tricks - here’s a roundup of the community’s favorite shortcuts.

  • Mac:
    • Command + Backquote: switch between windows in one app (eg different browser windows).
    • Command + Tab: switch to next most recently used app. Command + Shift + Tab to change in the opposite direction; hold Command then hit Tab to cycle through open applications.
    • Command + ~ (tilde): cycle through open windows in the current application.
    • Option + click green button in a window: maximize the window.
  • Windows:
    • Alt + Tab: switch to next most recently used app. Alt + Shift + Tab to change in the opposite direction; hold Alt then hit Tab to cycle through open applications.
    • Alt + D: go to the URL bar (in web browsers).
    • Ctrl + Shift + Esc: open Task Manager.
    • Windows key: open the Start menu with the cursor in the Search field.
    • Windows key + arrows: move application windows on the screen.
    • Windows key + D (or M): hide all applications, show the desktop.
    • Windows key + L: lock the screen.
    • Windows key + P: open a Project panel that lets you mirror your screen and extend it to other displays.
    • Windows key + X: open a “god mode” panel with links to common administrative controls like Power Options and Settings.
    • Windows key + Tab: open workspaces preview
    • F11: toggle full screen.

We also had one suggestion for Linux: Alt + Backquote to switch between windows in a single app (eg different browser windows).

One more tip: if you regularly use several operating systems, consider setting up keyboard mapping so your shortcuts stay the same across systems.

Should documentation have a formal tone?

Is there a requirement for formal tone in documentation? Or is it better for docs to be informal? We had a lively discussion on the topic this month.

Our documentarians were mostly of the ‘it depends’ school of thought here - as so often, there are no hard and fast rules. In particular, everyone agreed that the choice depends a lot on what your audience expects. It’s important that your tone should not be jarring, causing it to get in the way of your message.

What “informal” means can vary; going for a conversational style doesn’t require being irreverent. You can be professional and conversational at the same time, just as you might be when talking to colleagues or customers in person. Sometimes you’ll find that less-formal third-party material is more popular than the formal material written by the company itself. It’s possible that its more casual tone makes it more approachable.

A point in favour of formality is that it can simplify localization. Being too informal can make translation challenging, even more so if you’re using humour. The community was much more wary on the topic of humour: being conversational is one thing, but trying to be funny is a risk. “Documentation should not be about taking chances”.

How your tools affect your writing

Do you feel confined by your tools - do they block your writing? - or do you find them liberating? As we discovered in a recent discussion, it’s very personal.

Some find they’re distracted by the formatting possibilities in Flare or Word, preferring the simplicity of plain text or markdown: the constraints can be freeing. Other people find considering the styling (or, for DITA, the semantics) helps them think through the content and its meaning.

Thinking about formatting can help you look at your content anew - several said they reorganize the content when formatting. Similarly, regardless of which tool works better, many people felt that switching tools or even the medium (eg computer to paper) helps unblock them when they get stuck. It’s a trick to help your brain look at the problem differently. A similar suggestion (that we unfortunately could not possibly condone - Ed.) was to change your font to Comic Sans.

A philosophical question: is the style part of the content? Some see it as totally separate - a layer you add on top once the content is done. For others, the format isn’t meaningfully separate from the content: you can write without styling in mind, but when published, the styling will always affect the reader. In some types of writing the style is hugely important - for example, UI text.

What about bold and italics - are they styling? No, they’re markers of meaning: the style of italics represents the intent to emphasize something, regardless of the visual implementation. for example in HTML, using <em> (you can change the style but means the same) vs <span style="font-style: italic;">.

Job posts

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

Community events coming up

And that’s all from us. The newsletter team takes the next month off - so happy holidays, everyone, and see you all in February!

Announcing Write the Docs Portland 2020 Call for Proposals   Announcing dates for Write the Docs Prague 2020