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."
Whether it's your very first contribution to an open-source project, or you're translating our docs, or you're contributing a how-to recipe, or you're preparing the accompanying documentation for your new Astro feature... we have a guide for that!
Want to level up your open-source documentation skills? We even have guides for reviewing docs PRs: what we look for when we work with, and bring out the best in, your contributions to us.
If you want to contribute to @astro Docs, or you're looking for some guidance you can follow to create your own project's docs, we hope you'll find our resources helpful.