Home »

Write the Docs Newsletter – November 2019¶

Hello, everyone - it’s the November edition of the newsletter!

The Sydney conference is coming up in just a few short weeks, on 14th-15th November. Tickets are now sold out, but if you can’t make it, don’t worry - videos of the talks will be up on YouTube shortly after the conference.

Looking forward to next year, the site for Portland 2020 is live, as is the Call For Proposals. We’d love to hear all your awesome talk ideas, so get working on them! The CFP closes on 10th January, 2020.

Finally, we’re formalizing how we change policies, by introducing Write the Docs Enhancement Proposals. The community has mostly grown organically, but there have been some growing pains as we’ve expanded. Our processes are only loosely defined, which makes it harder for new people to understand who makes decisions and join in leadership positions. So we’re trying WEPs, an idea taken from the open-source ecosystem, to formalize our decision-making. If you’re interested, take a look at the introduction blog post, which goes into more depth.

Onto this month’s articles!

The strengths of different backgrounds¶

One of our most wide-ranging discussions this month put the breadth of documentarians’ educational and work backgrounds on full display. It made pretty clear that technical documentation draws folks with an incredible variety of education and experience. Here’s just a sample of some of the different backgrounds, and the strengths people feel they gained through them:

Culinary arts and restaurants: experience with managing stress, coping in sink-or-swim situations, and working with diverse groups of people
Customer support and tech support: lots of practice at explaining things; appreciation for the value of writing things down
Education: well prepared to develop training curriculum and knowledge base content
History, philosophy, religion, and ethics: strong reading, writing, and arguing skills, and especially the ability to write quickly
Library and information science: familiar with information architecture, tools, and technologies
Sociology and anthropology: keen human-centric insight and user-focused perspective
Technical writing certification or degree: allowed to grow into the role; driven to constantly improve

We could fill an entire newsletter describing the paths people took to their roles in documentation. But no matter how our documentarians all found their way here, we’re glad they did ❤️

Docs and design: When docs can’t fix all the things¶

Much as we’d wish otherwise, we don’t usually document perfectly usable software. (Is there such a thing?) And sometimes, the software we’re documenting has major usability problems. A plaintive question about how to document a poorly designed product generated a range of responses - from how to provide feedback about the design and try to improve it, to how to hide or make less prominent less usable portions of the product.

So if you’ve got features that “don’t make sense” or don’t seem to fit into the rest of the product you’re tasked with documenting, try these tips from our always-creative community:

See whether you can persuade the product dev team to remove not-very-sensible features, or features that seem to have been included by mistake.
Create an “Advanced Features” section of the docs and bury information about the features there.
Keep the docs about the problematic thing short, but also provide brief warnings about any consequences of trying to use a feature - for example, if it works poorly or has unexpected consequences.
Include a recommendation to contact Support before using the problem features (a bit passive-aggressive, but participants agreed that desperate times can call for desperate measures). If you do this, make sure to mention it to Support first!

The challenge of giving difficult feedback¶

Learning how to give constructive criticism - which often really means “negative feedback” - is really important, but not easy, especially with colleagues you don’t know well yet. A manager asked this month, and the community had this advice.

Firstly, giving negative feedback is painful, but you have to own it. Don’t distance yourself by saying you’re passing on other people’s feedback when you believe it to be correct. And putting it off won’t help in the long run. The longer you leave it, the more you’re tacitly approving, and the more of a surprise the feedback will be.

You can help by making the feedback about behaviour and its outcomes, not the person or how you feel about them. A useful acronym here is BIO: say what Behavior you’re observing (with specific examples), the Impact it has, and give Options for doing it differently. On the impact: for example, if a writer isn’t being concise enough, show how the longwindedness affects the reader. The extra information doesn’t help the user achieve their goals, and actually gets in the way.

And make sure you’re also giving positive feedback when your report does things well! It can be tough when the only feedback you hear from your manager is negative.

Finally, if you’re concerned about your report taking the feedback badly, it could be worth keeping documentation. If you’re getting complaints about your report from colleagues, get those in writing, and write notes of your meetings with them too.

“You”-sing the second person in documentation¶

Referring to the reader in the second person can make your writing feel more natural and friendly - but is it always the right choice? There are no hard and fast rules, but here are some guidelines.

In most end-user documentation, you can use the second person (“you should do the thing”) rather than the third person (“the administrator should do the thing”, when the admin is your audience). But there are some situations where second person doesn’t work so well. It might be less appropriate if you’re writing in a more formal context. If there are multiple types of readers / users of your system (for example, sysadmins and end users), it might be better to specify which one you’re referring to, as “you” could be ambiguous.

You can sometimes avoid specifying the person altogether by writing in the imperative. (eg, “To configure a new foo, use the set command.”) This is good as it’s clear and instructive, and often shorter. “You” and the imperative mood aren’t mutually exclusive as the second person is the only possible implied subject.

But only using the imperative can sometimes seem a bit curt. If you like using the second person, but you’re worried about having too many instances of the word “you” in a document, try mixing the second person with the imperative.

When in doubt, identify your audience, and see what your style guide has to say!