"4. You’re not just a writer, you’re an advocate for clarity

I thought being a technical writer meant simply explaining what someone else built. But it’s so much more than that. You’re there to simplify complexity, anticipate user needs, and advocate for clarity.

Why it’s key: A good writer doesn’t just document systems, they improve them. In most cases, you should be the first real user of a new feature. Your fresh perspective can highlight gaps and improve the overall experience."

https://bufferbuffer.com/10-things-i-learned-the-hard-way-about-technical-writing-in-tech/

#TechnicalWriting #SoftwareDocumentation #Documentation #Docs #SoftwareDevelopment

"Normally, you don't visit your own API documentation that often, right? I mean, if you already know how your API works, why would you want to consult its documentation? Conversely, there's a place you visit—or should visit—very often, with information you care about your API. I assume you have an API dashboard where you can review metrics such as the ones I described earlier. Usually, the dashboard lives close to the API gateway, or somewhere where other company-wide observability tools reside. What I'm proposing here, in short, is that the API documentation can be the best place to present those metrics to you, the producer.

Being able to see the metrics you care about right near the documentation for each part of your API feels refreshing. You could, for instance, be looking at the reference of one operation and immediately see its usage trend, the error rate, the number of active consumers in the last hour, and so on. What's more, some of the information visible only to you could also be actionable. You could, for instance, open the pending support requests to see what the top complaints are. Or, you could immediately check why there's such a percentage of errors on one single operation.

While most information would be restricted to you, the producer, I argue that some things could even be openly shared with your API consumers. Imagine being a consumer and seeing a list of "popular" API operations right on the documentation. Or understanding if a certain operation is producing a high error rate. All these things could be easily available in the API documentation."

https://apichangelog.substack.com/p/producer-oriented-api-documentation

#TechnicalWriting #APIs #APIDocumentation #SoftwareDocumentation #APIMetrics #APIAnalytics #SoftwareDevelopment

"[T]o build effective docs you not only need tools and content types, but also a model of needs that documentation must satisfy as a product, or of actions users need to accomplish through docs. This model should be fairly independent from the type of software product you’re documenting, in the same way conceptual models of product design and satisfaction abstract away the specifics. Aiming for a general model is necessary because it helps professionals learn and communicate together.
What follows is my own descriptive model of user needs for documentation, one I’m following to build and arrange documentation today.
The approach I’m proposing here is a model of what user actions the docs are meant to satisfy. The model aims at connecting both UX research and documentation frameworks with a conceptual and functional layer that focuses on two aspects: docs as a product and what users are meant to accomplish through them. It’s an attempt at describing what technical documentation should do. It’s treating docs as a product that someone is going to use to achieve actual goals.
As I said, the core of the model is actions. I’ve identified seven that I think cover a decent amount of goals that a consumer of docs may want to accomplish when using documentation. They represent common patterns in how users interact with documentation across different products and domains. They’re the following, each bearing an alternative term in parentheses: Appraise (Discern), Understand (Learn), Explore (Discover), Practice (Train), Remember (Recall), Develop (Integrate), and Troubleshoot (Solve)."

https://passo.uno/seven-action-model/

#TechnicalWriting #Documentation #TechnicalCommunication #UX #DocumentationFrameworks #UXResearch #DocsAsProduct

Although one can find a few good advices throughout this guide, It's clear that this was written by a developer and not by a technical writer.

Besides the inability to leverage from web typography - no italics or blockquote is used to clearly distinguish the examples from the rest of the text -, the author makes too many assumptions regarding the target audience.

For instance, in the case of copy-pasteable commands, I believe that real beginners appreciate the idea of entering one command at a time and they actually might be intimated with including " && \" in a command.

Last but not least, good examples should always come first and only then, afterwards the bad examples. In this sense, the approach followed here is not very pedagogical.

In the end, I quite liked reading this text because it really made my proud of my skills, experience, and knowledge as a professional technical writer :)

"Most software tutorials are tragically flawed.

Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. Other times, the author brings in hidden assumptions that don’t match their readers’ expectations.

The good news is that it’s easier than you think to write an exceptional software tutorial. You can stand out in a sea of mediocre guides by following a few simple rules."

https://refactoringenglish.com/chapters/rules-for-software-tutorials/

#TechnicalWriting #SoftwareDocumentation #Tutorials #SoftwareTutorials

"The quality of job descriptions varies wildly. That means how the job is described, the components of the job, and expertise expected for each component. The descriptions are better for the common job types, such as project and product managers, developers, and sales. Companies know what those are and have experience hiring those.

All that falls apart when it comes to writing, of any type, and specifically API documentation writers. CEOs, who I love to vilify for this reason, generally don’t understand technical writing and technical writers. To them, and that attitude often trickles down the table of organization, see copy, marketing, content, and technical writing as the same and interchangeable. I believe this causes the low pay rates, because we’re seen as a commodity, going at market rate. A doctor with 15 years of experience is treated as an expert. A writer with 15 years of experience competes in the marketplace with junior writers. A shame for sure. I digress some but that needed to be pointed out.

There is information to be mined from bad job descriptions, if you know what to look for and know how to use that information."

https://robertdelwood.medium.com/reading-api-documentation-writers-job-descriptions-92124e5d9008

#TechnicalWriting #APIDocumentation #APIs #SoftwareDocumentation #SoftwareDevelopment

"Writing For Developers: Blogs That Get Read is a practical guide to writing more compelling engineering blog posts.

We discuss strategies for nailing all phases of the technical blogging process: planning, drafting, revision -- even promotion and extension. And we have quite a bit of fun exploring the core blog post patterns that are most common across engineering blogs today, like “The Bug Hunt,” “How We Built It,” “Lessons Learned,” “We Rewrote It in X,” “Thoughts on Trends,” etc. Each "pattern" chapter includes an analysis of real-world examples as well as specific dos/don’ts for that particular pattern. There's a section on moving from blogging into opportunities such as article writing, conference speaking, and book writing. Finally, we wrap with a critical (and often amusing) look at generative AI blogging uses and abuses."

https://github.com/scynthiadunlop/WritingForDevelopersBook/

#TechnicalWriting #SoftwareDocumentation #Blogs #Blogging #SoftwareDevelopment

"The Good Docs Project is excited to announce our latest release of documentation templates! This version 1.3 is codenamed Friendship. The Friendship release is inspired by the twenty-seven bridges throughout the world named Friendship, including the pictured Thai-Lao Friendship bridge which connects Thailand and Laos.

One of the other big highlights in the Friendship template release involved the efforts by the Tech Team to standardize our template suite. Led by Bryan Klein, Michael Park, and Alyssa Rock, the Tech Team made several changes to the templates to improve downstream consumption. They standardized the template file naming conventions to ensure consistency, repaired broken links, and ran all the templates through a Markdown linter to ensure it was well-formed."

https://www.thegooddocsproject.dev/blog/release-friendship

#TheGoodDocs #SoftwareDocumentation #TechnicalWriting #SoftwareDevelopment

"Asking me what’s my favourite documentation is a bit like asking me what are the best doorways I’ve crossed in my life. We remember places, not open doors; we recall the things we did through software, not great docs. In my case, I seldom remember good or great documentation because its purpose is not to get in the way. On the other hand, I do remember lots of bad documentation when it failed to provide answers. The curse of technical writing is that the best expressions of our work are the ones people rarely notice, because they offer so little friction they never disturb the user’s flow.

There are exceptions to this, of course. The first is documentation that is presented in such a way that it generates a “Wow” moment. Perhaps it’s a code snippet you can run, an interactive demo, or similar gimmicks. While they’re not key to great documentation, they make for some memorable experiences, though that can backfire quickly if the docs aren’t good. The other exception are docs that teach us something new, either through conceptual explanations or examples. Some of the best docs I’ve read are aware that they’re also teaching new ideas and concepts. You can tell because they grin."

https://passo.uno/my-favorite-tech-docs/

#TechnicalWriting #SoftwareDocumentation #Docs #DocsAsCode #SoftwareDevelopment

"In short, APIs are how businesses speak to one another. Breaking this oath with a poor integration experience is a surefire way to reduce your business potential. By utilizing a source of truth and baking a specification-first approach into your API development and documentation practices, you more clearly communicate changes, reducing the possibility of broken clients and promoting forward compatibility. Great API products must be well-described, easy to understand, and predictable in the long run.

In the end, the business effects of specification-driven development are manifold. Whether you're building RESTful, GraphQL, or event-driven partner services, having reliable API documentation is important to compete in the digital economy. This consistency equates to a better partner experience, leading to stickier partners and less customer churn. By enabling smoother integrations and reducing frustration, spec-first documentation directly contributes to partner retention and loyalty, which ultimately drives revenue growth."

https://bump.sh/blog/how-spec-first-api-documentation-aids-partner-integration

#APIs #APIDocumentation #TechnicalWriting #SpecFirst #SoftwareDocumentation #Docs #DeveloperExperience #DocsAsCode

"So, if developers aren’t going to use Try Its, what harm is there for including them? They can just ignore them, right? Perhaps, but there’s more to it.

It takes up valuable screen real estate (the right corner above the fold). Writers need to optimize the developer experience, even to the point of minimizing eye movements. Make it easy to find details. That space could be used more productively.

We “should know” but we don’t. This segues into the real reason. It demonstrates that writers don’t know the developer experience. Let’s be blunt. We’re delivering documentation suites that have not been tested properly, calls that are unlikely to have been tested, and tools developers don’t use. Not understanding these issues is the fundamental reason writers also need developer experience. Writers simply can’t empathize with own audiences, which means we supplying developers with inadequate and incomplete tools and documentation. This is a real concern.

This is not a condemnation. Quite the opposite. API documentation writers need to empathize with developers. Writers do this by treating this as a craft, learn a little about development each day, and move slowly along the experience spectrum towards the developer’s end. Learn a language. It doesn’t matter which one. Java, JavaScript, to DOS batch commands, UNIX command line programming, Word macros, Python, or even AutoHotKey*. All of these have programming concepts and that’s what matters. Learn about them, which requires using an API guide, craft statements, and debug them is at the heart of the matter."

https://robertdelwood.medium.com/why-i-dont-like-try-it-f44112ed1b6d

#APIs #APIDocumentation #SoftwareDevelopment #TechnicalWriting

"There it goes: a customer pressing question makes its way to the documentation channel of your company. Someone suggests adding a question and its answer to a doc, perhaps an FAQ section somewhere. Folks will find it, search engines will rejoice, and support will have something to link to, even if it’s just a fragile question lost in the middle of other unrelated doubts.

That’s the moment where, as a tech writer, you must stop and intercept the thought of creating an FAQ. The goal isn’t to eradicate question-and-answer formats from the face of the planet (that’d be cruel), but to ensure information is organized thoughtfully and sustainably. After all, great documentation answers questions before users even need to ask them.

So, instead of FAQing things up, consider any of the following alternatives:"

#TechnicalWriting #SoftwareDocumentation #Docs #FAQs

https://passo.uno/what-the-faq/