"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

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