"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

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

"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/