Home »

Write the Docs Newsletter – July 2023

Aloha! There’s lots to cover this month, so let’s dive in.

Who makes up the Write the Docs community? What proportion support pay transparency? Where are salaries highest? How many have started a new job in the past 12 months? All these questions and more are answered in the 2022 Write the Docs Salary Survey results. Stay tuned: the survey for 2023 will be opening in early September.

In conference news, we recently saw the announcement of the speakers for the 2023 Atlantic conference. So check out all the interesting things you can look forward to learning. And the Australia conference has released the call for proposals and ticket sales so get ready for good times in December.

Away from the conferences and surveys, I’d like to extend thanks from all of Write the Docs to Daryl White. He has been coordinating the book club in #learn-tech-writing since January 2020 and facilitating many discussions. It’s been a tremendous benefit to many people to be able to learn about various aspects of technical writing together with others on a similar journey. I know it’s helped push me to read books and learn things I wouldn’t have otherwise. Thank you for your contributions, Daryl.

We have articles today on pushing back on overwork, getting info from others, documenting YAML files, and how much to disclose neurodiverse needs in interviews. We’re off after this for our semiannual winter/summer break. We’ll be back in September with more.

Pushing Back When You’re Overloaded

When you have too much to do, but new requests and assignments keep coming your way, what’s the most effective way to push back? The top tip is to ask your manager which tasks to deprioritize: “I can do this new task, but it means I will not have time for X, Y, or Z. Which of these would you like me to stop working on?”

Often, that discussion is enough to resolve the problem. But if your manager isn’t responsive, it becomes a matter of holding to your boundaries. In this case, consider providing your manager with a breakdown that describes each task, how long it will take, and why. You can point to this breakdown to answer questions about why tasks aren’t getting done. Task boards like Jira and Trello can help with this and also making others aware of the problem because reporters can be notified when their tickets are affected by new requests.

Another idea is taking a few days of vacation so that others have to fill in for you and learn by experience how overloaded you are. Or when you get an impossible request, respond by describing an alternative you can deliver instead of explaining why you can’t achieve the unachievable. If possible, take unclear requests off of your schedule until you understand the business need and requirements. A last resort is taking the problem to an intermediary like a colleague, another manager, or Human Resources.

When all else fails, you can continue working on tasks at a slow enough pace to prevent burnout, prioritizing as you go and doing your best to ignore unfair criticism and attempts to make you feel guilty. If important tasks are delayed because you’re overloaded, it might eventually draw enough attention to the problem to get it solved. If you’re worried about getting fired for taking this approach, consider spending the time you save on looking for a new job or finding some freelance work to mitigate the risk and help you get comfortable with moving on.

Getting Info from Others

A recent thread resurrected an enduring issue with documentarians: How do we get the information we need from experts? The May 2020 newsletter addressed this issue. The current discussion focused on how to ask questions of developers: what questions to ask and how to get the best responses for documentation.

People indicated that there are two levels of questions: 1) general, high-level questions; and 2) specific, detailed questions. Documentarians ask general questions to get an overall understanding of a product or domain. After we have the higher-level understanding, we can determine what detailed questions to ask. Specific questions fill in the gaps in our knowledge.

For general questions, you can ask product managers or customer support. Another potential resource could be any QA testers. We also have learning resources on the topic for interacting with people in other positions. If you’re writing end-user documentation, this knowledge along with your personal experience of the product may be sufficient.

If you’re writing for a more technical audience, you may need to approach subject-matter experts (SMEs; such as developers) for detailed information. See the 2020 article for interacting effectively with SMEs. A current poster mentioned that it’s important “to show you’ve put effort into figuring things out before taking up their time.” Another suggested asking very specific (not open-ended) questions based on your understanding because experts like to correct misunderstandings. In the 2020 article, this was indicated as Cunningham’s Law: “The best way to get the right answer on the internet isn’t to ask a question; it’s to post the wrong answer.”

Documenting YAML Files

YAML Ain’t Markup Language (YAML) is a machine-parsable data serialization language that is commonly used for specific tasks. YAML works well with native data structures and its syntax is independent of a specific programming language. It’s also designed for human interaction and works well with modern programming languages, making it a good choice for configuration and documentation.

To document YAML files, look at current reference documentation formats and tools. For example, JSON Schema and jsonschema2md are two viable options for describing schemas and configuration files.

OpenAPI documentation in YAML or JSON can also serve as an example of YAML configuration documentation. Consider OpenAPI as a resource to explore.

Many documentarians create example YAML configuration files using comments, placeholders, and links. They also use tables for lengthy references and some use PlantUML for YAML visualization. Writers also emphasized the significance of YAML schemas and the possibility of automated documentation creation. Some suggested using JSON Schema to design schemas, produce Markdown documentation, and use the JSON Schema Store to validate files such as for GitHub and Kubernetes configuration.

Overall, documentarians may improve their comprehension and communication of YAML configuration choices by reviewing current documentation formats, considering schema-based techniques, and leveraging tools and technologies.

Setting Up for Success as a Neurodivergent Person

A recent discussion involved whether as a neurodivergent person to mention any disability (and need for support) during an interview. A major concern was about being effective during the first few weeks of a new job. Three types of responses occurred: 1) bring it up during the interview, 2) discuss it with your manager after you’re hired, and 3) don’t disclose unless you can’t effectively do your job.

Those who prefer to address this during the interview based it on bad experiences after waiting. One suggestion was to ask relevant questions of the interviewer. Aim for general questions related to working style. Try to determine how supportive the environment is for people with disabilities and how accommodation-friendly they are. Before you get an offer, you should have a sense of whether the company is a “safe” space for you. (One interviewer suggested not disclosing because it’s illegal to consider that during the hiring process.)

If you wait to disclose, one thought is to not necessarily disclose a disability, but to communicate your needs to be an effective employee. For example, “I work best when I have external structure.” You can also ask about using certain scheduling tools, hardware, or methods to do your work. Explicit communications may be a key factor. In fact, some suggestions may help others on the team! In a supportive environment, your disclosure may elicit others to disclose their disabilities.

Some don’t disclose ever because of legal issues. Forcing an employer to address your disability may result in a decision that the company would NOT be able to reasonably accommodate it. A disability that prevents you from doing the work you were hired to do is not legally protected. Those that don’t disclose self-accommodate as best as they can.

Events Coming Up

Announcing Call for Proposals, Ticket Sales and the Grant program   Announcing Full Schedule