Write the Docs Newsletter – February 2018¶
Hi everybody! Kelly O. here – back in the saddle after getting through the whole OMG, it’s a different year now transition. I’m excited to report that we have a TON of stuff happening in the community. I guess we’re starting this new year off strong!
First things first, the march toward our Portland conference continues at a steady pace. May 6-8 is starting to feel awfully close, and we couldn’t be more excited. We’re working on confirming our last few speakers. You’ll hear from us with the full speaker line-up in the next week or so.
NOTE: If you’re not subscribed to the North American conference mailing list, you can sign up here.
If you’re planning on coming to the conference, but you’re not sure how to persuade your company to cover the costs, you might be interested in our new Convince Your Manager page. We’ve knocked together an example email and some resources that you can use to make your case.
And finally, in non-conference news, we’re thrilled to announce that the Write the Docs Job Board will be launching next week. One of the benefits of the WTD community has always been its ability to connect documentarians with employers who understand the value of good docs. The job board will be a destination for making those connections. Keep an eye on Slack, Twitter, the forum, your email, etc. – we’ll let you know as soon as it goes live.
Whew! Told you there’s a lot going on! But now, let’s have a look at a few of the conversations that have been happening in Slackland over the new year.
It’s not personal, it’s feedback¶
Have you ever needed to tell someone that their writing is… bad? How do you manage that conversation without being discouraging or unkind? Many in the community have been in this position before, and this month, the WTD hivemind had great tips for sharing feedback effectively and constructively:
- Follow the Toastmasters’ PIPS method: praise, improvement, praise, summary. Start with something they did well, explain what they can do to improve, move on to more praise, and then summarize. Including the praise helps your feedback land without damaging their confidence.
- Keep your feedback specific and results-oriented, and don’t forget the ‘why’. It’s helpful to couch your feedback in terms of the reader’s experience. Try something like, “I think users could misinterpret this to mean X instead of Y. Revising to Z would help prevent confusion.”
- Follow company culture. Depending on your team’s culture, folks might be fine with receiving a marked-up file of revisions, or they might expect to receive feedback during a collaborative discussion. Do your best to stick to established channels.
- Refer to outside sources. Use tools like style guides or checklists of common problems to handle proofreading and standardization issues objectively.
Want to chat more about constructive criticism? Head to #general on Slack.
Questions to ask during a job interview¶
A good job interview always comes down to the questions asked. But that responsibility falls not only to the interview*er*, but also to the interview*ee*. Last month, we had some excellent suggestions for how to ask intelligent, engaged questions at the end of a job interview:
- In general, be genuine and show curiosity. Don’t worry about demonstrating expertise – that’ll come later.
- Ask about processes and workflows: How do you release updates to the docs? Who decides deadlines? Who is considered the owner of the docs during the development cycle? Do developers write the first drafts or do writers? Etc.
- Ask about company culture: What is the day-to-day work like? When and how would you work with other teams?
- Ask how they define success: What’s required to be successful in this role? What would you expect from me three months after hire? Six months? A year?
- Ask how the interviewer feels about the company: What’s your favorite thing about working there? What the most frustrating?
As the interviewer responds, listen carefully to their answers. Do they sound informed and realistic? That’ll tell you whether they have a good grasp of the role they’re hiring for. Did they have good things to say about their own experience with the company? That should give you some sense of the company culture.
Overall, remember that the job interview is just as much about you assessing the company as it is about them assessing you.
Need more advice on the job hunt? Head to #career-advice on Slack.
Tech sites worth writing for¶
A lot of folks in our community do a mix of different writing types – including writing as a contributor for tech blogs and websites. To help people find more opportunities for publishing, Chris Ward (@chrisward on Slack) has started building a list of online publications that are good to write for.
Not only is this a good resource for any freelance folks out there, but it’s also a great opportunity to help build it up as a resource. You can find the list on Github here. Have a look, give it a fork, and add any publications that you’ve had good experiences with as a contributor.
Have a question or want to chat about the list? Pop it in #general and tag @chrisward on Slack.
Upcoming community events¶
Just in case we didn’t express enough excitement in the intro, here’s your friendly reminder that tickets for the Portland conference are going fast! Come join us May 6-8 at the Crystal Ballroom! Head over to the conference site to buy yours!
And to tide you over until then, we’ve got loads of meetups happening all over the world this month!
February 7 – Austin, TX, USA – Monthly meetup
February 8 – Melbourne, Australia – Getting devs to write good docs | Making Imposter Syndrome work for you
February 12 – Berlin, Germany – When in doubt, use C4
February 13 – San Diego, CA, USA – Swagger UI and the Open API Specification with Tom Johnson
February 19 – Amsterdam, Netherlands – Testing Documentation
February 20 – Dublin, Ireland – An introduction to effective corporate blogging
February 21 – New York City, NY, USA – Discussion: Managing Technical Writers
February 22 – Boise, ID, USA – First meetup of 2018
February 22 – Sydney, Australia – How to build an IA | Q&A: All things tech documentation
February 22 – Cambridge, UK – Markup languages: a brief history
March 1 – Los Angeles, CA, USA – First Pasadena Meetup
March 6 – Portland, OR, USA – Monthly Meetup
NOTE: If you run a meetup group and you’re not seeing your events show up here in this calendar, drop me a DM (@kobrien042) on Slack to let me know.
