#TechnicalWriting#SoftwareDocumentation#SoftwareDevelpopment: "With few books on technical writing, and even fewer trying to push tech writing into the minds of other professionals, TWfSD is an excellent, necessary book that capably bridges the gap between engineering and tech comms by directly addressing our partners in crime, software developers. I think both Chris and I would agree on making technical documentation a mandatory subject for Computer Science degrees, alongside modern DevOps and PMO techniques. This book could be the basis of a “Documentation 101” course in the syllabus of any modern CS degree (and I’d certainly pay to see Chris as the instructor)."
#TechnicalWriting#SoftwareDocumentation#Markdown#XML#DITA: "Think about how in Markdown you would ensure that “all our how-to guides must have an h1 title, followed by one or more paragraphs, followed by one or more steps to achieve the guide’s goal”, and then consider how easy it is in DITA.
This is just not really possible today, at least in any popular Markdown-based framework.
There is a path
Bridging the gap between Markdown and structured authoring will require building new tooling and standards. It’s unlikely that CommonMark or any other popular Markdown flavor would consider going in this direction, so we’ll have to create tools around Markdown.
We at Doctave have some ideas about how to achieve this, and have a roadmap on how to get there. At a high level there are a few things we would need:
✅ A parser and template system that is Markdown-aware
❌ A language for describing constraints and rules for your Markdown content
❌ An engine that enforces those rules on your content
We’re already part of the way there!"
#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.“
#TechnicalWriting#APIs#APIDocumentation#SoftwareDocumentation: "Your API is nearing completion and it’s time to let the world know about it. This means that it is time to complete your API documentation effort. But, where should you start? How do you know if you covered everything that your decision makers and developers will need to select your API and get started successfully?
This article provides a checklist to help you identify the documentation you will need for launching your API. We will also include some things to consider post-launch as well to help you continue to improve your documentation."
#TechnicalWriting#ProjectManagement#SoftwareDocumentation: "Why is it essential to establish a clear documentation workflow? How can developers, project managers (PMs), and techwriters work closely together without being a bottleneck? You may be familiar with these issues or looking for a better solution to make the customer and internal (in-house) documentation workflows more efficient.
The development of our workflow spanned about 4 to 5 years, during which we achieved smaller goals and had to adjust our plans along the way.
The actual implementation took 3 to 6 months, but this is surely not its final form. Our work environment and industry are always changing, so we need to keep experimenting to adapt quickly. Now, after reflecting on our progress and making adjustments, we've brought everything together in a more organized way. Even though we had the components ready, it still took a lot of effort to complete the whole picture."
#TechnicalWriting#ProjectManagement#SoftwareDocumentation: "Why is it essential to establish a clear documentation workflow? How can developers, project managers (PMs), and techwriters work closely together without being a bottleneck? You may be familiar with these issues or looking for a better solution to make the customer and internal (in-house) documentation workflows more efficient.
The development of our workflow spanned about 4 to 5 years, during which we achieved smaller goals and had to adjust our plans along the way.
The actual implementation took 3 to 6 months, but this is surely not its final form. Our work environment and industry are always changing, so we need to keep experimenting to adapt quickly. Now, after reflecting on our progress and making adjustments, we've brought everything together in a more organized way. Even though we had the components ready, it still took a lot of effort to complete the whole picture."