Blog - Posts tagged newsletter

Write the Docs Newsletter – December 2021

2021-12-06T00:00:00Z

Write the Docs Newsletter – November 2021

2021-11-03T00:00:00Z

Hi folks! November has somehow rolled around (already??) and it’s that newsletter time of the month again.

As promised last time: I’m super excited to let you know that the Salary Survey is now live. It takes less than ten minutes to complete, so please consider filling it out - you’ll be contributing to a really valuable resource for documentarians. All responses are completely anonymous, and we’re very careful not to publish any personally identifiable information (given the small size of the community). If you’re up for it, fill it out here.

Plus, great news from down under - we’ve just announced the Australia and India meetup will be on December 3rd. This “super-meetup” will be a two-hour event with four fab speakers, and will be free to attend. Sign up for the event here!

And with that, let’s take a look at what everyone’s been discussing on Slack…

Managing when your manager lacks docs experience

This month, our documentarians discussed how they have handled differences with a manager who has no experience with documentation. Among those who have worked for managers without a docs background, there were roughly two groups: the manager either deferred to the technical writer’s expertise or did not.

If your manager is in the first category, you’ll likely encounter less heavy-handed supervision, and docs-related disagreements may be rare. If your manager is in the second category, you have a harder path to tread, especially when your manager’s perspective on docs-related tasks doesn’t quite match yours.

In the course of this conversation, we learned a new acronym: HiPPO, meaning “highest paid person’s opinion.” In this context, the HiPPO method means ultimately disagreements between tech writers and managers are resolved according to the more senior person’s opinion, regardless of whether they have docs experience. When you are subject to the HiPPO method, your ability to affect docs-related decisions depends on how firmly you can gain your manager’s trust.

Even when your manager is inclined to trust your ability, you’ll still need to confirm their confidence by doing good work, cooperating with the rest of the team, and meeting deadlines. This approach is the best path you can take with managers who don’t grasp your ability either – demonstrating that you understand and can document complex processes might be the only way you can get traction.

Options for single-sourcing

Single-source publishing is a content management technique that lets you use one source of content but publish it to different output formats (“write once, publish everywhere”). It’s not something that every team needs, but it can be super useful if you need to publish to the web and PDFs, or if you have many similar variants on one product. If your team is not “technical” - more specifically if they are unfamiliar with version control software like Git, lack software development skills, or have no way of obtaining the support necessary to implement a docs-as-code approach, component content management systems (CCMS) like Paligo and MadCap Flare might be more suitable.

Regardless of the method you choose, decide on a single-source publishing strategy and consider the advantages and disadvantages of each option to determine which is ideal for your team. Distributed contributions, for example, may be a reason to choose the docs-as-code method. In contrast, if you use Flare or a docs-focused CMS like Knowledge Owl, you’ll find more robust support for reusing articles or snippets. Whatever method or tool you choose, have a plan in place to ensure a successful single-source publishing approach.

Documentation gets respect (or at least attention)

Two recent reports highlight the increased attention documentation seems to be getting in the worlds of software development.

The 2021 State of DevOps report from Google Cloud includes data showing the effects of docs quality on devops team performance, and describes practices to improve the quality of your documentation. The report is based on seven years of research and data from more than 32,000 professionals worldwide, focusing on “capabilities and practices that drive software delivery, operation, and organizational performance.” So the focus is not on docs – but the report includes good documentation as one of six findings characteristic of the 26% of teams studied who fall into the highest performing category. This is _internal_ documentation, and its quality has a statistically significant impact on how secure, reliable, and effective a team’s devops practices are. Quality documentation efforts should include critical use cases for products and services, guidelines for updating and editing existing documentation, clearly defined ownership and responsibility for documentation, inclusion of docs as part of the software development process, and recognition of docs work during performance reviews and promotions.

The State of Software Quality API 2021 report from SmartBear similarly points to “accurate and detailed documentation” as a key aspect of the overall success of an API, second only to “ease of use” for API consumers. Disappointingly few survey respondents rated their API docs as “Very Good” – but only 16% of teams include technical writers for their API docs. On the other hand, more than half the respondents contribute to API docs in some way, and 60-70% of respondents work for companies that include a formal API documentation process – but only about half of those companies consider documentation a priority. Respondents cited a range of obstacles to providing quality documentation, but they all fell into the larger category of insufficient resources – time, tools, personnel, budget, and more. On another front, our documentarians who so diligently work with OpenAPI definitions will be happy to read that OpenAPI usage continues high, but GraphQL and AsyncAPI continue to grow in popularity.

What we’re reading and listening to

The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Please join us in the #bipoc Slack channel!

This month’s articles are intersectional. They touch on topics that intersect gender identity and people of color.

A short read: A topic of discussion that’s come up in the Write the Docs Slack, is it ok to address a group of people as “you guys”? Baron Schwartz sums up arguments from the internet and offers some alternatives.

A medium read: In the article Stop Telling Women They Have Imposter Syndrome from the Harvard Business Review, Ruchika Tulshyan and Jodi-Ann Burey talk about the myth of Imposter Syndrome and how it’s disproportionately hurting women of color in the workplace.

A longer read/listen: This year the McKinsey and Company’s Women in the Workplace report highlights that women, while making some gains in the workplace, are still facing challenges when trying to rise to higher levels. This is especially true for women of color. Despite the increase of self-reported white allyship and an increase in DEI initiatives, women of color report continued micro-aggressions in the workplace and little allyship action from their peers.

From our sponsors

This month’s newsletter is sponsored by Gateway Translations and JetBrains:

Gateway Translations makes it easy for tech writers to get started with localization.

Finding the right translation tool with integrations for easy workflow & file compatibility
Translators with technical backgrounds for 45 languages
Trusted by GitHub, TIBCO, Fortune 500s

Book a free consultation.

'And what is the use of a book,' thought Alice 'without pictures or conversation?' Tech documentation is also more appealing and easy-to-read when illustrated. What visuals do we insert in our docs? What tools do we use to create and edit them? Help us by taking this survey, and we’ll be happy to share the results with you.

Take the survey

Interested in sponsoring the newsletter? Take a look at our sponsorship prospectus.

Featured job posts

Technical Content Writer, Webiny (Remote)
Senior Technical Writer (Web Developer), Sitecore (National Capital Region, Canada)
Senior Technical Writer, Synctera (Remote - US or Canada)
Senior Technical Writer, Privacera (Remote - US)

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

Virtual events coming up

09 November, 08:30 EST (Florida, USA) - Morning social
09 November, 19:00 MST (Calgary, Canada) - A crash course in content reuse
16 November, 18:00 PST / 21:00 EST (USA) - A conversation with the authors of Docs for Developers
17 November, 19:00 EST (Toronto, Canada) - Write the Docs Toronto
23 November, 08:30 EST (Florida, USA) - Morning social
03 December, 15:00 AEDT (Australia) - Virtual super-meetup: WTD Australia and India 2021

Write the Docs Newsletter – October 2021

2021-10-05T00:00:00Z

Hello everyone!

It’s Beth here, writing while I’m listening in to Write the Docs Prague. I hope everyone who attended had a great time! For those of you who couldn’t make it, keep an eye out: we’ll be publishing the talk videos on YouTube fairly soon. And if you’d like to get more of a flavour of the conference, you can listen to the intermission music - which I am bopping along to as I type :D

And one more thing to keep your eyes peeled for - the Salary Survey is going through its finishing touches. We’re really excited to be continuing this work to improve transparency around documentarian salaries, so watch this space!

In the meantime, we’ve had another month of interesting conversations and insights from the Write the Docs Slack. Read on, and enjoy!

Docs review strategies for lone writers

Being a company’s only technical writer comes with advantages and disadvantages, but a common challenge for lone writers is getting reviews for documentation. When there’s no established docs review process and there are no other documentarians to turn to, here are some strategies the lone writers of Write the Docs use to get the work done.

You may be able to publish your best efforts without review and await (or seek) corrections, whether from users or others at your company. Docs have bugs just like code, and speedy fixes may be more within your control. The downside with this approach is any mistakes are public until you fix them.

The fastest way to get corrections may be to publish errors, but sometimes that’s not an option. In this case, try to assemble an informal group of docs review resources. Seek a product manager or subject matter expert to review docs for accuracy. For readability, look for someone else whose job requires writing, perhaps in marketing or communications. Your experiments here could help drive support for a more formal docs review process.

Some lone writers solicit docs review by creating feedback channels in Slack with the Workflow Builder. For example, you could create a #documentation channel with a built-in form for submitting correction requests, with fields for specifying the page in question and the requested corrections. Then the Slackbot can notify you when someone submits a correction.

For detailed instructions for setting up your own docs feedback workflow in Slack and other insights from this discussion, read Darryl J. White’s blog post Editing and Gathering Feedback.

Equipment you find useful for working remotely

What are the most useful tools for working from home? This question sparked a lot of conversations this month, but top of everyone’s list was multiple monitors. The simple ability to see more than one thing at a time is hugely helpful, and the benefits of improved productivity and less window-switching have made them essential for work-from-home life.

Other recommended tools mentioned were sit-stand desks and computer accessories like comfortable wire-free mice and keyboards. Aside from hardware tools, software applications like Grammarly, macOS’s Voice Memos, and BetterSnapTool proved beneficial for working from home. Even traditional tools, like a whiteboard and pen and paper, were brought up.

With so many software and hardware tools available, it can be challenging to pick the ones that are worth putting in the metaphorical “toolbelt.” However, whether you want to be more organized or keep track of important meetings, there is always the right tool for the remote job.

What’s in a documentarian resume anyway?

As anyone who spends much time around the Write the Docs community knows, the questions around just who writes the docs, what their job titles might be, what their skills and experience might be, have no single definitive answer. One of our longest recent threads about job descriptions and resumes explored a number of possible answers, though. Here’s what we took away from the 100+ message thread:

Writers and hiring managers alike struggle with whether to focus on docs-specific skills – writing, tools, workflows – or on specific technologies in search of docs. Folks seemed to agree, though, that a documentation position that requires familiarity with the specific tech to be documented needs to emphasize required skills. And finding just the right fit is a challenge whether you’re hiring or looking to get hired.
Writers with non-writing backgrounds can prefer not to list specific tech on their resumes, especially coding, for fear they’ll be considered overqualified or otherwise not the right fit. Other writers are reluctant to mention specific tech if they’re not experts, for fear their skills will be challenged, or assumed to be greater than the writer feels they are.
Some writers emphasize their ability to learn new tech – they consider themselves generalists with strong research skills and experience picking up new areas sufficiently to be able to document them well. Others emphasize their skills in specific technical areas – they consider themselves specialists with the ability to take on non-writer work as needed, especially in QA, design, UX, or support. Curiosity and eagerness to explore and learn were attributes everyone seemed to agree are vital, whichever approach you choose.
Job seekers: be thoughtful about what you put on your resume, don’t rely on LinkedIn alone, and try to tailor your job searches to companies you think might be a good fit for what you want to do – whether it’s tech you want to learn, tech you know a little about, or tech you know a lot about. Cover letters can help you show how you fit a job listing, beyond what you put in your resume.

If you’re interested in pursuing the conversation, join us over at the GitHub Discussion one stalwart WTDer started. Carry on, folks!

What we’re reading and listening to

The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Please join us in the #bipoc Slack channel!

In the United States it’s Hispanic Heritage month.

A short read: From Courageous Conversation, do you know the difference between Hispanic and Latino?

A longer listen: From MPR news, How the term Latinx, and other labels, miss the mark. This episode talks about labels such as Latinx, BIPOC, etc, and explores where they started, what they mean, and who uses them.

Featured job posts

MDN Senior Community Manager (1-year fixed term), MDN (remote - Germany)
MDN Senior Technical Writer (1-year fixed term), MDN (remote - Germany)
Programming Writer, DigitalOcean (remote)
Technical Writer (IntelliJ IDEA), JetBrains (remote)
Developer Educator, Aiven (remote)
Technical Writer (YouTrack), JetBrains (remote)
Technical Writer, Inductive Automation (remote - US)
Technical Writer, Aiven (remote)
Technical Writer, Entado (remote - US)

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

Virtual events coming up

11 October, 19:30 IDT (Israel) - Python for Documentarians
12 October, 08:30 EDT (USA) - Morning social
13 October, 12:00 AEDT (Australia) - Findability in the world of docs
21 October, 19:00 PDT (USA) - Roundtable: New to the field!
21 October, 19:00 EDT (Canada) - Write the Docs Toronto
26 October, 08:30 EDT (USA) - Morning social

Write the Docs Newsletter – September 2021

2021-09-07T00:00:00Z

Write the Docs Community Update - August 2021

2021-08-13T00:00:00Z

Hey there documentarians!

Eric Holscher here, one of the co-founders of Write the Docs. The newsletter team is taking August off this year, but there’s still plenty going on in the community. This update covers what else is going on behind the scenes while the newsletter team takes a much deserved break.

We’re looking forward to seeing everyone online for our virtual Prague on October 3-5 in the CEST timezone. We’re also getting excited about our upcoming virtual Australia & India conference on December 2-3 in the AEDT timezone. The talks were just announced for the Prague conference, and the Australia & India conference CFP is open until August 31 if you have ideas to present.

We also had our second virtual Portland conference in April this year. It was another success with almost 700 people attending from all over the world. The videos from the conference are now available online.

Write the Docs Enhancement Proposals (WEPs)

We have had a WEPs for a little while now, but they haven’t seen a ton of traction in the tumultuous last 18 months. There are a couple of exciting updates to report though.

We have approved our Slack Moderation WEP, which defines the process for moderating Slack much more explicitly. The more formalized process can help grow our moderation team, and reduce confusion about the roles and responsibilities involved. We strive to keep the community friendly and inviting, and moderation is a necessary part of that work.

We have also just launched a new organizational structure and governance WEP, which will help to shape the structure of how Write the Docs operates. This WEP will define all the various teams in the community, as well as how decisions are made at the organizational level. The proposal adds the concept of a Community Council, which will be made up of the team leads of all the community teams. The Community Council will make many decisions around the community, allowing more people to share in the official leadership structure.

We hope that more people in our community will participate in the WEP process, so please read through the proposal and give us feedback.

Write the Docs community shop

We’ve heard from some of the folks in the community that they are missing all the swag we used to give away at our conferences. We always had lots of little goodies to give folks across the years, including stickers, notebooks, shirts, hoodies, and other bigger items in some of our raffle giveaways. We’re excited to be able to bring back a small version of that for those of you who want to wear your documentarian pride on your sleeves :)

The Write the Docs Store is now live with lots of good things. We have stickers, mugs, phone cases, bags, prints, and notebooks with these designs:

Docs or it didn’t happen swag in dark & light
Sketchnotes from all the talks at our Portland 2021 conference
Community logos which provide a simple way to show your WTD pride

We have tried to find a vendor which has reasonable shipping costs so that we can keep the costs down for our community, but it can still add up. We recommend trying to do a group purchase with a meetup or company so that you can reduce the costs involved, and get a few different options of the various items. If you also want a bulk order of stickers or similar swag for a meetup, we can also directly ship them to you for free if you email us at support@writethedocs.org.

Salary Survey

The annual salary survey, run by the Write the Docs community, aims to gather data about salaries for people working in documentation and related fields around the world. Results of the second survey are available on our website.

We hope that this data can help our community members determine what appropriate salary ranges are, and provide a benchmark for future employment-related decisions and negotiations. Additionally, we’re hoping the results spark discussion of employment-related trends and issues in our industry, including but not limited to the effects of the COVID-19 pandemic.

We’re hoping to launch a 2021 survey here soon, but haven’t put the finishing touches on it quite yet. Watch the newsletter for that in the coming months.

Featured job posts

Technical Content Developer, Vectorized.io (Remote)
Senior Technical Writer, Galvanize (Bangalore, Karnataka, India)
Technical Writer - Product Documentation, Upbound (Remote)
Technical Writer 3M (Remote)
Tech Writer for the domain-specific language (DSL) documentation, Superface (Remote)

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

Thanks

Thanks again for subscribing to our newsletter and for being a member of our community. We hope to see you soon at one of our online events, on our slack, or continue to see you here via this newsletter.

You can always reply to this email if you have any questions or comments. Stay tuned for another newsletter update next month!

Write the Docs Newsletter – July 2021

2021-07-06T00:00:00Z

Good morning, afternoon, or evening, documentarians! It’s Beth and the newsletter team with a last summer update before we head off on a little break. We’ll be back in September :)

The main announcement for the month is that the CFP and ticket sales have opened for the Australia and India conference! As with our other conferences this year, it’ll be held online, and the dates for that are 2nd-3rd December. The CFP is open until 15th August, so get thinking about talks you’d like to submit!

Onto our stories from Slack…

What’s best for your images - JPG or PNG?

JPG or PNG? Which is the best format to use? Does it even matter which you pick? Well, the Write the Docs community has chimed in to answer your pressing questions, and it seems like PNG is the clear winner. Portable Network Graphics, or PNG, offers unmatched clarity for screenshots in online docs and doesn’t degrade when opened and saved like the alternative JPG or JPEG. Compression in PNG is also better since it’s a lossless image format and not a lossy one like JPG, meaning it preserves all of an image’s details. Another advantage of PNG is that it supports transparency, whereas JPG is best for gradient images.

Curious to know if there’s something better than PNG? There is, and it’s called WebP, a format that works for both lossy and lossless compression. If you have a tool that exports to WebP, use it instead of PNG or JPG for enhanced web images. Otherwise, stick with PNG for clear, detailed, high-contrast images.

For more help choosing the right format, check out this article by Allison Boatman or this one by Shane Melaugh.

Designing a tech writer career ladder

What does a technical writing career ladder look like? This month while discussing how to set one up, we saw a few examples - GitLab’s technical writer ladder, and career-ladders.dev/docs. Some community members saw value in aligning title levels across functions. So a standard progression applied to tech writing could look something like this:

Associate Technical Writer / Technical Writer I
Technical Writer / Technical Writer II
Senior Technical Writer / Team Lead
Staff Technical Writer / Manager
Principal Technical Writer / Director
Distinguished Technical Writer (?!)

Many felt including “Distinguished” was a bit unusual. It’s nice to have it there to have something to shoot for - to show what a tech writing role can look like at that level. But it’s okay for a company just not to be able to support someone at that level, when Distinguished usually means people who have an ecosystem-wide or industry-wide impact.

Even the other high levels can be challenging to reach, especially as an individual contributor. Many companies need managers much more than high-level ICs, or simply don’t have scope to do work at such a high level. But there was general agreement on the importance of having clear standards for what each level means. It can be really frustrating if someone wants to get promoted but the ground keeps shifting.

How long should it take to reach the “senior” level? Surprise surprise, there’s no clear answer. We see 5 years mentioned a lot in job adverts, but some folks said it took as little as 2 with the right domain knowledge. Of course, seniority shouldn’t purely about the number of years you’ve been in the role - most felt it was more to do with your skill level, and the breadth and level of responsibility you take on. Take these titles with a pinch of salt, though, because what they mean can vary wildly between different companies. For on what it means to be senior, see Distinguishing between junior vs senior tech writers from the June 2018 newsletter.

Doc history and Git

When you’re creating a new version of docs for a release, how important is it to keep the docs for old releases? The simple answer is to keep all history, just in case - you never know when you’ll need it. But some docs are so outdated that the original writeup is incredibly unlikely to be relevant.

How to keep the history depends on how you want to use it. If you’re using Git and you just want to be able to check the history, you can see it with git log. Though it can take some archaeological work to follow the trail when files get moved.

But what if you want to publish those old docs? One option is to copy your old files alongside your new ones. It’s possible to copy the files while retaining their history, but it takes some effort. However, be aware that Git doesn’t track files exactly. It tracks some content (blobs—sequences of bytes), and trees of file names that point to blobs, but it doesn’t actually track those things together, which is why that blog post has to use merges to copy the history. It’s fighting the way Git wants to work. It might be simpler to copy the file with a commit message saying where it was copied from, to help someone track down the history if they need to.

If you can publish from something other than HEAD, you can do something much simpler: just use Git’s tagging system to mark the commit for an old release, and then publish from that tag. Some teams use different branches for different releases, which would make this even more straightforward.

What we’re reading and learning

The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Please join us in the #bipoc Slack channel!

A short read: This article on Axios talks about LinkedIn starting to pay ERG leaders, usually a volunteer position, for their work.

A medium read: this Great Place To Work article highlights strategies to improve inclusion and equity in the workplace.

For a much more in-depth exploration (several weeks), Coursera now has two free courses on Anti-Racism offered by the University of Colorado, Boulder: course one and course two.

Featured job posts

Senior Technical Writer, Squarespace (New York, NY)
Technical Writer, Socure (Remote - US)
Technical Writer (Chinese Traditional), Gandi Asia Co. Ltd (Taipei / remote possible)
Senior Technical Writer, Appian (Remote)
Developer Documentation Lead, Chainlink Labs (Remote)
Senior Technical Writer for Developer Documentation, Avalara (Brighton, UK)

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

Virtual events coming up

06 July, 8:30 EDT (Florida, US) - Morning social
13 July, 19:00 MDT (Calgary, Canada) - Write the Docs Calgary Meetup
14 July, 12:00 CDT (Texas, US) - Virtual lunch social
15 July, 12:00 EDT (Florida, US) - GitLab for technical writers
15 July, 18:00 EDT (Indianapolis, US) - Summer Meet and Greet
20 July, 8:30 EDT (Florida, US) - Morning social

Write the Docs Newsletter – June 2021

2021-06-03T00:00:00Z

Hi everybody! It’s Beth here, writing to you from my gloriously sunny balcony (thank goodness rainy May is over). I hope you’re all enjoying the weather wherever you are.

The big thing I want to shout about this month is the Prague Call for Proposals. If you were even sort-of entertaining the thought of submitting a talk idea, take this as your sign to go for it! My favourite thing about giving a conference talk is the conversations the talk starts. It’s awesome for helping you find people who care about the same things as you; so if there’s something you’d really like to see a talk about this year, I really encourage you to submit your idea. And if you’d like a bit of help working on your proposal idea, the EMEA WTD meetup is hosting a proposal workshop and discussion on 10th June - check it out.

On to the stories from Slack! This month we’ve been talking about prioritization, the challenges of having busy colleagues, and much much more.

Priorities: Document new features or improve existing docs?

What would you prioritize: customer-requested improvements to existing documentation or working on new feature documentation? We discussed it on Slack this month as an interview question; for many documentarians though, the tension between prioritizing new vs. existing docs is a day-to-day reality. Mostly, this means prioritizing which to work on first - because neither releasing new features without documentation nor neglecting to update existing documentation are good options.

One reason to prioritize new features is if they are difficult or impossible to use without documentation. In this month’s discussion though, prioritizing improvements to existing docs had the most support.

When you prioritize improvements to existing documentation, you raise the bar for new docs. The quality of your documentation rises as new docs are written to the higher standard. Making improvements implies figuring out what’s wrong to begin with, so you’ll be able to fix problems instead of repeating them. It’s also easier to overlook or even forget low-quality content, whereas missing docs for new features are obvious. It makes sense to address existing customers’ frustrations with existing docs. Even when poor docs do not represent a safety concern, they discourage current and potential customers. As one writer put it, “bad documentation is like breaking a promise”.

It’s not just about keeping users happy, though, because your work has a business impact beyond providing the necessary documentation. For example, technical writers serve as a proxy for new users, so they can provide valuable insights from a user’s perspective. The informal testing that writers often do during the documentation process can uncover bugs and usability issues to pass along to the product team. And good docs encourage self-service and reduce the number of customer support contacts. The benefits of good documentation spiral out to many other aspects of the business!

Restricting docs to authorized readers

A long-time community member started a new job recently, and among the novelties to explore they’re figuring out how to allow only authorized users access to some of the docs.

The community had plenty to suggest. Options ranged from suggestions of platforms, to details of how to roll your own or integrate different identity providers or workflows. They also mentioned making sure the solution was well-documented for future contributors to the docs!

Here are all the options folks contributed to the discussion:

If you’re writing docs in Confluence or knowledgebase articles in Zendesk, both tools support limited access
You can implement per-location authentication requirements in an NGINX server. This supports SSO with JWT (Json Web Tokens)
Netlify offers an identity and RBAC (role-based access control) solution
Work with a combination of feature flags and allowlists
In Apache, you can use the .htaccess config file and user credentials
KnowledgeOwl lets you specify which pages users can see without logging in (or what Google indexes), with groups to manage access
Last but not least, Redocly offers a RBAC option for configuring developer portals

Dealing with busy stakeholders

How do you finish the documentation for a feature when a key stakeholder is too busy? What can you do to get the information you need from an unavailable stakeholder before the project’s deadline? This month, the Write the Docs community discussed ways to progress on documentation projects when dealing with an unavailable stakeholder.

First, try writing as much as you can before contacting the stakeholder for help. This allows you to provide detailed information when emailing them about the hold-up. If the question is time-sensitive, it’s well worth including a preferred deadline for an answer. As an alternative, try finding another stakeholder who has the knowledge and time to answer your questions. If, despite your efforts, the stakeholder remains unresponsive, you could notify your manager so they can speak with the stakeholder’s manager. Finally, consider taking time to build rapport via light and informal chat with the stakeholder. Discussions that aren’t just about chasing them for help can help establish a trusting relationship, and relieve tension and frustration.

Although these suggestions may help, it is important to remember that there is no one-size-fits-all solution when dealing with too-busy stakeholders. While a simple conversation may resolve some issues, others may necessitate escalation. It’s okay to find this difficult - these situations can be complex and stressful!

There are more tips in this blog post by Ian Haynes, and we’ll close with one point from there: if you can, stay positive and professional, to avoid burning any bridges. With luck, you will get the information you need!

The state of software documentation

If you’re interested to get a sense of the overall state of software documentation, you’re in luck, because we had some great resources shared this month. There’s a lot of handy data about how docs are perceived, by both our developer audiences and by the folks who write the docs, with particular detail in the space of API documentation.

DigitalOcean Currents Q3 2018 report - in particular, “What factors does your company consider while making business decisions around when to use open source for a particular project?”
SmartBear 2020 State of API report, and Tom Johnson’s analysis of this report
Postman 2020 State of the API report
The Content Wranger’s 2019 State of Technical Communication
Tom Johnson’s 2020 Developer documentation survey

What we’re reading & listening to

The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Join us in the #bipoc slack channel!

For a short read: This twitter thread from @HeyChelseaTroy breaks down why approaching inclusion like other business initiatives often fails.

Have a little more time: Check out this article on CNBC about ways you can show support for your Asian American colleagues. Even though this starts with news about Anti-Asian American violence, the advice about support can easily be applied to anyone in need.

If you have 50 minutes: Check out this episode of WorkLife with Adam Grant featuring John Amaechi. The two talk about building an anti-racist workplace with a key takeaway of: “your culture is defined by the worst behavior you tolerate”.

Featured job posts

Technical Writer, Software Engineering, Pomerium Inc (Remote - North America)
Technical Writer, Carted (Remote - Sydney, Australia)
Technical Writer, Vistar Media (Remote - New York)
Content Lead, NetSpring Data, Inc (Remote - Mountain View, California)
Senior Technical writer for APIs, ALIAS/CODE IS LAW (Remote - CET or EST)
Technical Documentation Writer, Chainlink Labs
Senior Technical Content Writer, ThousandEyes (a part of Cisco), (Remote - London, UK)
Senior Technical Writer, Schrödinger (New York or Portland)
Technical writer, Kandra Labs (Zulip), (Remote)
Digital Transformation with the TAAP No Code Low Code Applications Platform, TAAP (Remote)
Senior Technical Writer - Distributed US, Cockroach Labs (Remote)
Technical Evangelist, Developer Experience & APIs, Envestnet (Raleigh, NC, USA)

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

Virtual events coming up

08 June, 8:30am EDT (Florida) - Morning social
10 June, 7pm CEST (Europe) - EMEA Write the Docs Proposals Workshop and Discussion
16 June, 12pm AEST (Australia) - Docs as code - Part 2
21 June, 7pm EDT (Detroit) - Using Notebooks for Documentation
22 June, 8:30am EDT (Florida) - Morning social
24 June, 7pm CEST (Europe) - Open source tools for API documentation

Write the Docs Newsletter – May 2021

2021-05-04T00:00:00Z

Hello, Write the Docs people! There’s tons to cover this month, so I’ll get straight to it.

We’ve just wrapped up our second virtual Portland conference - thanks so much of you to all who attended for making it special! If you missed it (or just want to experience it all over again), all the talks are now live on YouTube.

There’s plenty more conference goodness still to come in 2021, with the Prague virtual conference coming on 3rd-5th October, and we’ve just announced that the Australia and India virtual conference will be 2nd-3rd December. And the Call for Proposals for Prague is open now. Really looking forward to hearing your ideas - big or small, inspiring or entertaining.

Finally, we’re proud to announce our 2021 donation matching campaign. We want our work to make a difference globally, and we want to encourage Write the Docs members to engage with their local organizations. So please check out the matching campaign blog post, and if you’d like to donate to a relevant charity, get in touch.

Podcasts for documentarians

If you’re looking for podcasts about technical writing, content strategy, knowledge management, and related topics, here’s a list courtesy of the WTD community (with links for podcasts with dedicated websites). The number and variety of podcasts for documentarians is a delight!

Folks noted one gap: podcasts from non-English-speaking countries or in languages other than English. We have a couple in this list, but if you know of others, please share them in the WTD Slack!

General tech writing and interviews with documentarians:

Content strategy and copywriting:

Humor:

JustsayIT, Technical Writers’ LAUGH

Tech writing and technology:

The Manuscript (from Brazil)
Towards a Smarter World

Tech writing training topics:

UX writing:

Writers in Tech

The grammar of singular they

Using “they” in the singular has a long history. But the grammar is not always obvious - as a recent Slack question showed. What is the appropriate reflexive form of “they” - for example, the equivalent to “he himself is” or “she herself is”?

There was some disagreement on whether it should be “themselves” or “themself”, and so, correspondingly, what the verb form should be also – “they themselves are”? or “they themself is”? Interestingly, nobody suggested “they themself are”, even though the most common verb form for singular they without the reflexive pronous is “are”. But one person pointed out that “the person themselves is …” is not uncommon. So many possibilities! So little agreement!

Some, understandably, suggested omitting the reflexive form altogether. This can be appropriate in technical writing, if you can find a way to rephrase - for example, by writing less formally to provide the emphasis that the reflexive pronoun can sometimes carry.

Everyone did seem to agree that the singular they (and the gender-neutral language it represents) is here to stay - and that this is a good thing. Some folks admitted to struggling when people expressed preference for “it” as a personal pronoun – but again, there was general agreement that it’s important to make the effort. Language changes! (Or, as one contributor put it, “be the change you want to see in language!”)

Making accessibility more accessible

Accessibility is an evergreen topic in the WTD community. The latest batch of shared resources inspired a group of folks to update the list we publish, and to revise the style guide as well in the process.

So here are the new pages! Thank you to everybody who contributed discussion and links in the Slack, as well as to the brilliant collaborators who put it all together during the conference Writing Day (so your newsletter people didn’t have to do the work ;)):

Accessibility guidelines: for writing and beyond
Reducing bias in your writing (formerly included with accessibility, but deserves its own page)
Style Guides in general

What we’re reading and watching

The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Please join us in the #bipoc slack channel!

For a short read, check out this article in Good Housekeeping about why some Asians are having a hard time speaking out about the ongoing Anti-Asian hate crimes and how you can show support.

If you have a little more time, read this article on Forbes for some ways you can be a BIPOC ally in the work place.

And if you can invest more than an hour, take the time to watch this webinar from Virginia Tech about Black Technical and Professional Communication. It explores topics on Black User Experience Design, Black Entrepreneurship, Black Rhetorics of Heath Communications, Black Activists as Technical Communicators, and more.

Featured job posts

It’s been a busy month on the jobs board - tons of great opportunities out there!

Senior Information Developer, Appian (Remote)
Customer Success Engineer, Cased (Remote - US)
Information Developer, Appian (Remote - McLean, Virginia)
Documentation Engineer, Tropic Square (Remote - Prague, Czechia)
Technical Writer / Documentation Specialist, Rebilly Inc. (Remote)
Technical Writer, Semaphore (Remote)
Technical Documentation Writer, Chainlink Labs (Remote)
Technical Writer, Schrödinger (New York or Portland)
Content Lead, Macrometa (Remote - USA or Europe)
Technical Writer, Instabase (San Francisco, California)
Technical Writer / Editor (Quantum Computing), D-Wave Systems (Burnaby, BC, Canada)
Staff Technical Writer, Illumio (Sunnyvale, California)
Technical Content Manager, Starburst Data, Inc. (Remote)
Technical Writer, Juniper Networks (Remote)
Customer Success Manager, Zoomin Software (Remote)
Technical Writer, Prisma (Remote)
Technical Writer, Starburst Data, Inc. (Remote)
Technical Writer, Server, MongoDB (Remote - New York)
Education Engineer, Realm, MongoDB (Remote - New York)
Senior Product Manager, Documentation, MongoDB (Remote - New York)
Software Documentation Writer, Flox (Remote)
Technical Writer, Software Engineering, Google (many US locations)
Manager, Technical Writing, Google (many US locations)
Technical Writer, Cloud Technologies and Tools, Google (Waterloo, Ontario)
Technical Writer, Juniper Networks (Sunnyvale, California)
Manager, Technical Writing, Google Kubernetes Engine, Google (Waterloo, Ontario)
Open Source Engineer, Slack (Remote or several on-site locations)

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

Virtual events coming up

11 May, 6:30pm MDT (Calgary, Canada) - May 2021 Write the Docs Calgary Meetup
12 May, 12pm AEST (Australia) - Docs as code - Part 1 | Lightning talks
13 May, 6pm CEST (Stockhom, Sweden) - Not Just a Number: Design Against Ageism
18 May, 6pm CDT (Central US) - WTD East Coast Quorum: The Future of Illusions
19 May, 7pm EDT (Toronto, Canada) - Write the Docs Toronto
10 June, 7pm CEST (Europe) - EMEA Write the Docs Proposals Workshop and Discussion

Write the Docs Newsletter – April 2021

2021-04-01T00:00:00Z

Write the Docs Newsletter – March 2021

2021-03-05T00:00:00Z

Hey everyone! It’s your friendly neighbourhood WTD newsletter team, with our March edition.

Spring is here and the year is racing on, and can you believe it’s getting close to conference time? We’ve just announced speakers for our virtual Portland conference, which is coming up on 25th-27th April. If you think those speakers look great (which of course you do!), get your tickets now.

And if Portland isn’t soon enough for you, the West Coast Quorum meetup is holding its first virtual event this month! The event is about “The Product is Docs: A Look Inside” and will be held on Thursday 18th March at 19:00 Pacific Time. If you’re interested, sign up to attend.

This month we’ve seen a quite a number of style guide and “how do I write this” discussions, so we’re trying something new: a newsletter on a theme! We hope you enjoy it :)

A best practice by any other name…

Is there an alternative for the term “best practices” in documentation? It’s a commonly used and understood term (not to mention a commonly searched term), but sometimes it doesn’t quite fit. It can sound authoritative – who’s to say that anyone knows the best practice for everyone else’s environment? Also, best practices can change over time: what works best right now might not work as well as the months or years go by. And when users really need proscriptive instructions, best practices are probably too imprecise for the occasion.

If best practices are too inexact to satisfy user needs, try to reconfigure the information-formerly-known-as-best-practices as a narrow range of scenarios with a single solution. For example, instead of “Best practices for software installation, configuration, and testing”, try topics like “Choose the installation method”, “Configure the agent after installation”, or “Confirm the agent is correctly installed.” This covers the information users need and provides a definitive pathway they can follow.

For a straightforward terminology swap with a less-authoritative tone, consider these suggestions:

Good practices
Tips (and the variation “implementation tips”)
Guidelines (and the variation “implementation guidance”)
Proven methods
Recommendations

These alternatives might work in some situations, but it’s difficult to find an all-purpose replacement that readers will understand just as handily. For better or worse, “best practices” is meaningful because it communicates a common idea in any context without requiring wordy explanations. The search for an ideal replacement continues…but if you’ve grappled with this question yourself and came up with a better term, please do share it in the #general channel!

And etcetera and et cetera. And so forth …

Are documentarians for or against latinisms like etc? A recent question on this produced a remarkable consensus - the newsletter team are so used to the answer “it depends”!

So: don’t use “etc” was the fairly unaninmous response: it’s just too likely that readers will not know what it means. However, there was much less of a consensus on what to replace it with. Some, in the spirit of the widely recognized ban on latinisms, simply translated it into English, most commonly into “and so on.” Others recommended writing around the term, typically in the form “such as <example_1> or <example_2>” to replace “<example_1>, <example_2>, etc.”

Most agreed it’s not worth making special effort to edit for only this offense. As some said, “it’s in the backlog’s backlog’s backlog …” So while nobody seems to like “etc”, most acknowledged they let such things go more often than not, unless thez can see that these terms have become real stumbling blocks for users.

How to indicate UI elements

What’s your style for marking UI elements in text? It’s common to want to emphasize that something is (for example) a button so it stands out, whether you write it as the Save, Save or Save button. Why? It helps users to scan the document; and if your button is well-named, it should also match up to something the user is trying to find for the task at hand. Plus if UI text is in sentence case, this can result in confusing phrasing in docs, and emphasis can help the reader parse the sentence.

The difference between bold and italics isn’t huge, but there is a bit of a choice here. Some contributors to the conversation felt that bolding really jumps off the page, and was the fastest way to get the reader’s attention. (It’s also what the Microsoft Manual of Style recommends.) In contrast, italics are a little subtler, and maybe better used for more general emphasis. Regardless of which you choose, you may want to mark up UI elements with a specific class or inline style, to make sure they’re always styled the same way.

You’ve got to be a little careful, because a page filled with one or both types of emphasis gets pretty noisy. It’s one reason that just following a style guide might not be enough - sometimes it’s a judgement call about what makes a doc too busy and distracting.

Featured job posts

DevRel Engineer - Documentation, Teleport (remote)
Documentation Lead, Hiro (remote)
Technical Writer, Datacoral Inc
API technical writer, Upvest (contract, remote)
Documentation Manager, Timescale (remote)
Content Developer 2, Microsoft (remote / Redmond)
Part-time Documentation Contractor, Tidelift (contract, remote US)
Technical Content Writer, Load Impact AB (remote)
Information Developer (Technical Writer), OpenFin Inc (remote / US / UK)

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

Virtual events coming up

08 March, 5pm GMT (Ireland) - Virtual coffee chat
09 March, 6pm EST (Ottawa) - WTD Ottawa Shopify Meetup
09 March, 7:30pm MST (Calgary) - March 2021 Write the Docs Calgary Meetup
10 March, 12pm GMT+11 (Australia) - Remote: GitHub Open Source docs | The Doc Product Owner
16 March, 8:30am EDT (Boston) - Morning social
18 March, 7pm GMT+1 (Barcelona) - Git Basics Workshop with Anna Skoulikari
18 March, 7pm PDT (West Coast US) - The Product is Docs: A Look Inside
30 March, 8:30am EDT (Florida) - Morning social
13 April, 8:30am EDT (Florida) - Morning social
13 April, 6pm EDT (Ottawa) - WTD Ottawa Shopify Meetup
17 April, 7pm EDT (Toronto) - Write the Docs Toronto

Blog - Posts tagged newsletter

Write the Docs Newsletter – December 2021

The work documentation really requires (it’s not all writing!)

Deciding what to work on next

Answers to “Why are good docs important?”

Standards in documentation tooling

What we’re reading and watching

From our sponsors

Featured job posts

Virtual events coming up

Write the Docs Newsletter – November 2021

Managing when your manager lacks docs experience

Options for single-sourcing

Documentation gets respect (or at least attention)

What we’re reading and listening to

From our sponsors

Featured job posts

Virtual events coming up

Write the Docs Newsletter – October 2021

Docs review strategies for lone writers

Equipment you find useful for working remotely

What’s in a documentarian resume anyway?

What we’re reading and listening to

Featured job posts

Virtual events coming up

Write the Docs Newsletter – September 2021

Avoiding the dreaded “wall of text”

Where are all the junior positions?

The basics you need to document an API

Documenting hardware: different from software?

What we’re reading and learning

From our sponsor

Featured job posts

Virtual events coming up

Write the Docs Community Update - August 2021

Write the Docs Enhancement Proposals (WEPs)

Write the Docs community shop

Job Board & Newsletter sponsorship pricing updates

Salary Survey

Featured job posts

Thanks

Write the Docs Newsletter – July 2021

What’s best for your images - JPG or PNG?

Designing a tech writer career ladder

Doc history and Git

What we’re reading and learning

From our sponsor

Featured job posts

Virtual events coming up

Write the Docs Newsletter – June 2021

Priorities: Document new features or improve existing docs?

Restricting docs to authorized readers

Dealing with busy stakeholders

The state of software documentation

What we’re reading & listening to

Featured job posts

Virtual events coming up

Write the Docs Newsletter – May 2021

Podcasts for documentarians

The grammar of singular they

Making accessibility more accessible

What we’re reading and watching

From our sponsor

Featured job posts

Virtual events coming up

Write the Docs Newsletter – April 2021

Addressing the user as “you”

Dealing with the myth that people don’t read docs

Reading times on articles

Improving your editing

What we’re reading/listening to/watching

From our sponsor

Featured job posts

Virtual events coming up

Write the Docs Newsletter – March 2021

A best practice by any other name…

And etcetera and et cetera. And so forth …

How to indicate UI elements

From our sponsor

Featured job posts