#TechnicalWriting#TechnicalCommunication#Docs#SoftwareDocumentation: “We know that the decision to make a purchase or maybe to buy more of your product is heavily reliant on the kind of technical content you have and whether the users see that what you have is what they need from a functionality and capability perspective. This is throughout the user journey. If a user is just browsing around for a solution, if you have better content than your competitor, they’re most likely to come back to you. If they’re on the verge of just onboarding, they will use technical content to onboard, and so on and so forth.
What we are seeing is that documentation portals, which is the home for technical writers, are actually becoming the number one traffic for a company’s users. If you know how to measure that and you can actually see that linear growth in traffic, and you know that part of this traffic is people making a decision to buy your product, this is definitely something that you want to surface up to your leaders and justifies an investment in making your content better. That’s just one example.
Another example, which is another value metric that we often measure, is returning users. What we’ve seen is that when people visit your documentation often, and even to be more specific, more than twice in the previous 30 days, they’re twice as likely to actually become a paying customer.”
Tech writing is unlikely to disappear. The sector where we’ve seen the biggest growth in recent years is computing: writers have always been present in software and hardware companies since the 60s. But even in highly regulated sectors, such as aviation, manufacturing, and pharmaceutics, docs are a necessity for legal and compliance reasons. You could call those the bastions of our craft.
The pace of change in tech is increasing, though, in no small part due to the advent of large language models and an increased emphasis on automation. Better UX also means that user docs are seen as less necessary, with docs priorities shifting towards more technical products that often require development skills. “How can I transition to dev docs?”, a fellow writer asked me the other day.“
I've been helping to investigate a few LLVM and Rust bugs recently, and I keep running into pet peeves with how these bugs are reported, so I'm going to put together some #RulesForBugFiling
I don't want to discourage anyone from filing a bug, please do! But... be aware with how you represent the issue that you're seeing.
I also know that there are folks on here who are vastly more knowledgeable than I am, so feel free to suggest corrections, perhaps by filing some sort of report...
You can add a bit of JavaScript to automatically activate the relevant tab based on the reader's operating system, so they see the relevant info sooner.
📗 The dated Lucida Grande was the Mac system font a decade ago and used for the docs on Mac (and only Mac). We now use the system font stack, to get a similar result to Linux, Windows, Android and iOS. https://systemfontstack.com
To make them more visible, we've added coloured sidebars and text to the "New in version x.y" / "Changed in version x.y" / " Deprecated since version x.y" directives.
Some excellent #docs at https://bpmn.io/toolkit/bpmn-js/walkthrough/#bpmn-js-internals by @bpmn_io. I know NOTHING about any of the technologies, and yet that diagram makes it looks like something understandable. Simple clear sentences like 'We use diagram-js to draw shapes and connections' help too.
Thanks to #mdbook, I'm well on my way to finally completing my private #wiki / #docs for all things #tech: home network, desktop, mobile, code snippets and so on, guides I'm sure I'll be glad I can easily reference again someday.
Boost to save a writer's life: you can block that fucking @ popup on GoogleDoc newlines (they added it super recently) by hacking your adblocker. Basically add "docs.google.com###docs-instant-bubble" as a new line in your My Filters list on uBlock or similar.
#TechnicalWriting#SoftwareDocumentation#Docs#Documentation#SoftwareDevelopment: "You may wonder: how can I write technical content? Do I need to be a great coder? Do I need to have a background in writing? Let me answer those last two questions now: no. Writing is all about communication, as I discuss throughout Software Technical Writing: A Guidebook. If you have some technical skills and enjoy refining your communication skills, you have the mindset you need to write technical content.
Software Technical Writing: A Guidebook starts with an introduction to the role of a technical writer. The book then discusses guidance for writing, covering topics from clarity to style to code snippets. Finally, the book discusses how technical writing fits in with the rest of an organisation.
This book is written for people who want to start writing technical documents, or who are early in their careers and are looking to refine their skills. With that said, no matter where you are in your journey with technical writing, Software Technical Writing: A Guidebook contains tactical guidance you can use in your work."
#AI#TechnicalWriting#SoftwareDocumentation#Docs#GenerativeAI: "If it’s really true that tech writers spend only a small fraction (~20% of their time) writing, then introducing power tools that speed up writing isn’t going to replace the tech writer. At most, AI tools might make a tech writer 20% more productive. However, tech writers have a brand problem. Regardless of how much time we spend doing heads-down writing, most people think we sit around writing all day.
Some might think tech writers are stalling the AI implementation in an effort to deflect job replacement. I don’t think that’s the case. Nearly every tech writer group I meet is actively trying to identify where and how they can implement AI tools in a way that works. Most are scratching their heads, finding only a few odds-and-ends type of scenarios — not the core work. Especially at the senior tech writing level, most projects and bugs involve a level of ambiguity and complexity that’s not easy to automate by feeding instructions into a machine."