Here's one for the tech writers, writing about tech writing: #TechWriting #TechnicalWriting

"The following are my suggestions regarding what else to consider for each of Daryl White’s excellent questions about choosing a toolset for documenting a software product or project.

I have appended a brief guide to the main/broad categories of documentation toolsets and some of the platforms/components that are popular in each.

Finally, this resource ends with a table of possible solutions for various scenarios you might find yourself in.

Before we start with the existing list of questions, I want to highlight one that I think is most important of all, but which is often assumed by people who create these kinds of guides, as they tend to come from one or another world already.

What are you documenting?

When it comes to software technical writing, the more appropriate way to ask this might be: For what user roles is your documentation intended?

For graphical end-user interfaces (GUIs), the largest range of docs tooling is available, but here some of the more commercial turnkey tools have most of their advantages.

For administrator interfaces (installation, configuration, etc), again any tooling will work, but we start seeing real advantages for lightweight markup, codebase integration, and version control.

For developer interfaces, docs-as-code offers significant advantages. Developers can better contribute directly, and it’s generally friendlier for coded samples. APIs (native and remote), SDKs, and CLIs are almost certainly best documented in a docs-as-code environment, even if you integrate it with a more conventional platform for end-user docs."

https://gist.github.com/briandominick/d4cbe11228de0ebe31cda630976af4ef

#workaholic here. Would be nice with a side job, or similar, that I could do, well, on the side, or during the weekend?
Any ideas.
Probably best in #tech or #coding but can also do #AudioEditing or #TechnicalWriting

IDK what I'm going for here, but why not haha

"The accompanying diagram is intended to help you quickly decide how to document an API, but particularly a REST API. The first split is just to make sure you are looking for the right kind of API.

Here is some more context to help you decide on an approach and get started."

https://gist.github.com/briandominick/3ffab6be460fbde799aa34e0a42a4299

"No one’s heard of a starving craftsman, just starving artists, and for a reason. Craftsmen create something people need. You’ve mastered a few important skills and moved up in the company. The important aspect here is that as you reach out to a greater community, you realize that there are plenty of people who are more skilled than you and who are still learning. Learn from them.

Gaining textbook skills or collecting certifications isn’t the point anymore; it’s applying all this knowledge in practical ways. Along the journey, you need to watch out for your best career interests and make sure that what you’re doing is what you want to do. For example, many get lost in promotions that lure them away from what they like doing, whether that’s programming or writing.

Finally, don’t underestimate perpetual learning. This is the key to the long road. Take time to practice, even if your job doesn’t seem to allow it. Learn new skills or apply existing skills in new ways. Along with practice comes failure, but don’t let that discourage you."

https://robertdelwood.medium.com/book-review-apprenticeship-patterns-guidance-for-the-aspiring-software-craftsman-808c95ee478e

I've been setting up my portfolio with Hugo and experimenting with different themes and layouts. Here’s a quick write-up on how I started and some lessons learned along the way. Feedback is always welcome!

https://techwritingcx-hanku-lees-projects.vercel.app/insights/how-i-started-hugo/

"[E]ven thinking about the right approach for documentation, apart from the documentation artifact I end up producing, is a form of thinking. And this is my larger point, more than the specific logic of my actual argument. Deciding on the approach is a form of thinking that technical writers engage in. Even when we use AI tools to streamline documentation, it doesn’t mean we’re removing ourselves from thinking and reflection. As long as we’re still engaging somewhere, I think Warner would approve. In this way, we use AI tools to augment and amplify the scope of our thinking, not reduce it."

#AI #GenerativeAI #Writing #TechnicalWriting #SoftwareDocumentation #TechnicalDocumentation #TechnicalCommunication

https://idratherbewriting.com/blog/jonathan-warner-more-than-words-book-review

"How do you deal with code snippets in blog posts getting outdated?"

Every time I give a talk about blogging for developers, I'm asked this. Now I started to take action with the first iteration of the solution.

I added version metadata to my blog posts and display them at the start of the post.

https://hamatti.org/posts/track-software-versions-for-technical-blog-posts/

I'm wrapping up a project, strategic & self-paced. It's been rewarding, but the finish-line push is killing me. I need to submit it. I can take it only so far on my own. Still, it's so big that I'm always finding something to fix. Dang it, today is the day.

When we built tooling to audit the code examples in our documentation, we had to decide how to access the data. We had a rough idea of what content we wanted to audit, but implementation required more than a rough idea. We also had to decide how to work with this content and what to do with the resulting data.

This is part three in an eight-part series about auditing the code examples in our documentation.

https://dacharycarey.com/2025/03/16/audit-access-data/

#TechnicalWriting
#Documentation
#DeveloperDocs

I am constantly surprised at which blog posts do well, and which ones flop. I put a bunch of effort into writing a detailed tutorial for a tricky technical topic that can help programmers in their day-to-day work, and it flopped. I brain-dumped a personal story about why I'm going to do a thing, and it was a hit.

This article about 'invalidating management styles' really resonates with me as I recently have had a year where any initiative that I showed (and there were many) was met by a manager who said ' that is not what we need' or 'our engineers won't like that' or the other myriad problems he can find with my initiative. The worst response was 'there's too much of you in it' (translation: they don't want me to present, but he can present).

I ended up being out of ideas and miserable. All along I was networking within the organisation and found a secondment with another team. On the 1st morning a depressing weight lifted off my shoulders. I never expect perfection in others, but I love this team and its managers. We even have lunch together at least once a week because we enjoy each other's company .
#TechnicalWriting #WriteTheDocs

https://www.theguardian.com/commentisfree/2025/mar/16/a-managers-flat-response-to-gails-initiative-left-her-deflated-feeling-seen-is-fundamental-to-human-wellbeing

Hire more technical writers: Isn't the solution obvious?? :-D

"Documentation was especially valuable when it came time to refactor code by providing a blueprint that saved time and improved focus. The researchers found that good documentation “ensures that refactoring efforts are directed towards tangible and specific quality improvements, maximizing the value of each refactoring action and ensuring the long-term maintainability and evolution of the software.”

As our co-founder Joel Spolsky put it, documentation encodes generational wisdom that goes beyond the simple specs of what was built. “Think of the code in your organization like plumbing in a building. If you hire a new superintendent to manage your property, they will know how plumbing works, but they won’t know exactly how YOUR plumbing works,” said Spolsky. “Maybe they used a different kind of pump at their old site. They might understand how the pipes connect, but they won’t know you have to kick the boiler twice on Thursday to prevent a leak from springing over the weekend.”

If we know from decades of research that documentation is a key component of creating and maintaining quality code, why is it so often considered low-priority work developers would rather avoid if they can be writing code instead?
(...)
By embracing AI-powered documentation tools, development teams can significantly reduce toil work, mitigate technical debt, and foster an environment where developers can thrive. Wise organizations will also keep humans in the loop, ensuring that documentation engineers or technical writers act as editors and stewards of any AI-generated documentation, preventing errors or hallucinations from creeping into otherwise accurate docs."

#Documentation #SoftwareDocumentation #TechnicalWriting #SoftwareDevelopment #Programming

https://stackoverflow.blog/2024/12/19/developers-hate-documentation-ai-generated-toil-work/

"[T]he lack of a clear entry path makes the profession less accessible, contributing to a lack of diversity in tech writing teams. If technical writing is to remain relevant in an industry that values innovation and inclusion, it needs to welcome new voices.

Fixing this problem won’t happen overnight, but there are steps companies and the broader industry can take to rebuild the pipeline for entry-level talent:

- Reintroduce mentorship programs.
- Companies can pair senior writers with juniors to share knowledge and help newcomers build confidence.
- Redefine “entry-level” roles.
- Stop asking for years of experience in entry-level job postings. - Focus instead on transferable skills like writing, research, and adaptability.
- Create apprenticeships or internships.
- Paid opportunities to learn on the job can give aspiring writers the experience they need to land full-time roles.
Invest in training.
- Documentation teams should have budgets for upskilling new hires — not just hiring pre-trained professionals."

https://willkelly.medium.com/how-the-technical-writing-profession-betrayed-entry-level-tech-writers-8a0c05617efd

"Tech comms can be a business, but thinking is not selling: it requires intellectual freedom and courage. Leaving these conversations to engineers risks turning technical communication into a caricature of itself, a four-quadrant fantasy devised to lure developers into thinking that documentation is a simple pastime, yet another Jira task.

Only independent thought can help us progress and navigate uncertainty, including our future in a world where AI is injected into every domain that deals with words. Technical writers must own their problems and the conversations around them, or they will slowly fade into irrelevance, their problems absorbed by other disciplines that have more pressing problems to focus on. And if you’re reading that we should lobby more, you’re not wrong: defending knowledge requires power.”

#TechnicalWriting #TechnicalCommunication #SoftwareDocumentation #CriticalThinking

https://passo.uno/tech-writing-depth-issue/