Write the Docs Newsletter – August 2017¶
Hi folks!
This month’s issue is coming at you from the sunny Bohemian countryside. I’m in the Czech Republic this week visiting family, but next month, I – and several hundred of you – will be back for Write the Docs Prague 2017! Things are getting very real, in conference-planning land, and you can check out what’s on the docket for the main stage in our newly published talk schedule!
In other news, Slack’s been humming away as usual this month, with so many excellent conversations that it’s getting harder and harder to choose just a few to cover here. We’ve also got nine different local meetups happening around the world this month. So even if you can’t join us for the conferences, don’t miss out on your other opportunities to interact with the community!
Oh, and also, as I mentioned last month, we’re looking to expand our little editorial team for the newsletter. Special thanks to Claire Lundeby (@claire.lundeby), who’ll be joining the crew this month! We’re still looking for one or two more folks who already hang out on the Write the Docs Slack, and want to help us turn insightful conversations into mini-features. Drop me a message on Slack @kobrien042, if that sounds like you!
In the meantime, let’s see what people were talking about this month!
What resume advice is the right resume advice?¶
For anyone currently job-hunting, this story will probably be pretty resonant. The question arose, this month, of how to navigate the virtual ocean of resume guidance, tips, and templates out there, and decide which advice is the best advice. Since most of us have been in this position before, there were lots of helpful suggestions:
- There is no ‘right way’ to write a resume. All of the mechanical and organization rules depend on you, your background, the job listing, the target company, etc.
- Treat your resume like any other kind of documentation – start by asking who your reader is, and what they need from your resume. Align your content to the themes and priorities present in their job listing/any other company materials you can get your hands on. Try a keyword density tool for help identifying those themes.
- Don’t limit your resume to your paying work. Include personal and community projects – stuff you work on in your free time or as a side hustle. Just because you’re not getting paid, doesn’t mean you’re not gaining experience. (XP > GP)
- Make sure you’ve got your supporting materials in hand. Craft a tailored cover letter for every job. (No form letters!) Get your LinkedIn profile in shape. Spruce up your portfolio; even if you’re just starting out, write up some samples for your favorite tool or process.
- Apply for the right jobs. Job hunting takes a HUGE amount of effort. Better to invest that time into perfecting a few really exciting applications, than putting minimum effort into dozens of applications you don’t really care about.
Jobs and careers are a pretty common theme on the WTD Slack, so we’ve set up a new channel – #career-advice – to better fill that need. Come hit us up with all your job-hunting, or general career advancement questions!
READMEs and doc-driven development¶
Poorly written documentation is pervasive among GitHub repos. Past and upcoming WTD conference talks and earlier Slack threads bear witness to our community’s recognition of the problem and our efforts to address it. But it continues to be difficult for developers to jump over to the documentarian role, especially after development gets rolling.
One participant suggested this README maturity model to help guide documentation efforts. Others mentioned side-stepping the problem altogether with documentation-driven development.. Even if you’ve never heard of it, you can probably guess what it means: you write the documentation before you write the code. Writing comments and the README in advance forces you think through what the code should do and helps you see your product from the user’s perspective. It’s like test-driven development, but with docs!
See The Art of Documentation and Readme.md from API the Docs London for more. Or, if you’re heading to Write the Docs Prague, check out one of the README-related sessions!
Accessible docs, colorblindness edition!¶
A variety of questions come up when we try to improve the accessibility of our documentation. Is our link text descriptive enough? Do all our images have alt text? Is our navigation usable from a variety of device types? Are we using semantic markup to our advantage/the advantage of our readers? This month, another accessibility question floated to the surface: How do we make our docs friendly to colorblind readers? As always, the community had a bunch of great suggestions!
Colorblindness can affect not only the effectiveness of our screenshots and other graphics, but also the visual experience of our documentation on the whole. For a primer on how to think about colorblindness in doc design, this blog post (from a web designer’s perspective), is a good starting point. In general, we’re looking for high-contrast, visual cues that aren’t strictly color-dependent (texture, shape, etc.), and a color palette that looks tolerable to as many eyeballs as possible.
For that last point, it can be hard to imagine what colors might look like to the various kinds of colorblindness. But this is the internet; there’s tools for that! Folks suggested a couple of different options, including Color Oracle, a desktop simulator for the different types of colorblindness, and Color Hexa, which provides a wealth of information about any color you look up, including how it appears for various types of colorblindness.
Making docs maintainable¶
This month the WTD hivemind tackled one of the holy grail questions: how do we establish a truly maintainable docs system? No surprise that we couldn’t come up with a definitive set of practices, but folks contributed a wealth of great practical tips:
- Implement well-structured information architecture
- Automate as much as possible, especially in areas of rapid change, and make sure that automation scripts are easy to maintain Examples: code includes, API reference docs, screenshots
- Make it easy to find and update groups of related topics
- Create and promote a lightweight style guide
- Stick to an “Every page is page one” approach
- Use templates to make writing new content easier for new and returning contributors
- Set up doc sprints (onsite or remote) to help focus groups on a predefined set of docs issues
- Set up continuous integration/continuous deployment on doc builds to promote an agile attitude toward doc contributions and fixes
- Make the process for contributing as simple as possible
As with all our stories, this conversation will continue to evolve on Slack, so if you have a favorite tip for or example of a maintainable docs system, definitely hop on Slack and share it!
Upcoming community events¶
PRAGUE CONFERENCE COUNTDOWN: One Month Left!
We’re likely to sell out in the next few weeks so get your tickets ASAP! And if you already have yours, don’t forget to go check out the full talk schedule!
Upcoming Meetups
August 10 – Denver, CO, USA – Embracing Change: Staying sane in docs and support
August 14 – Austin, TX, USA – Git the Docs: Learning Git in a safe space
August 17 – Montreal, QC, Canada – Social Meetup
August 21 – Houston, TX, USA – WTD video: Even naming this talk was hard
August 23 – Fredericton, NB, Canada – Documententarian Meetup at Trailway Brewery Co
August 28 – Boise, ID, USA – Networking Night!
August 29 – Brisbane, QLD, Australia – Content 101 + How Tech Writers Can Help Make Designs Safe
August 29 – Hamburg, Germany – Let’s talk about translations
September 7 – Salt Lake City, UT, USA Coffee Klatch
