#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."
#HTML#CSS#Hugo#WebDev#TechnicalWriting#SoftwareDocumentation#SSGs#StaticSites: “If you’ve ever wondered how a website works and whether or not you could build your own, this book is for you. The Static Site Guide walks you through the process of building a website from scratch by using hands-on examples. You’ll learn what a website is and how some of the most popular website technology works. By the time you reach the end, you’ll have built your very own website, and you’ll know how to do it again on your own.” https://www.staticguide.org/
It all comes down to helping your API consumers integrate faster. When people decide to integrate with your API, they have a job they want to get done. They think your API could be the fastest path to solving it. But too often, building an integration with the API is as painful (or even more painful) as the original job. That’s counterproductive, to put it mildly. There are a hundred things your users would rather be doing than reading your API docs and writing basic integration code. The less you require of them, the happier they’ll be. And SDKs are the best tool for making sure your API remains unobtrusive.
The definition of an SDK is straightforward: It’s a library that surrounds your API and handles the boring parts of the integrating process, such as:
Constructing an HTTP request
Managing an authentication token
Handling retries
Parsing paginated responses
More powerful SDKs will go beyond request and response-handling basics and provide type safety and hinting in the integrated development environment (IDE). This means users don’t have to open a docs page; they’ll get all the information and feedback they need directly in their coding environment. It doesn’t get more efficient than that."
#APIs#APIDocumentation#DX#TechnicalWriting#SoftwareDocumentation: "Finding the right balance between being too simple and too sophisticated isn't easy. You might get away with a generic onboarding how-to guide if your API focuses on one single feature (as OpenCage does). Otherwise, you need to craft different onboarding experiences for each one of the consumer use cases you want to support.
One thing that works for me is learning as much as I can from consumers before writing any API documentation. Then, I focus on the top use cases potential consumers are interested in. Since those will be the top entry points for most new API users, I prepare a tutorial for each. Each tutorial offers a safe environment where developers can easily sign up to use the API. Then, by following the steps in the tutorial they will end up implementing the integration that fulfills their use case."
#TechnicalWriting#SoftwareDocumentation#Documentation: "Even if you have the same title, you can have different experiences with your career and learn different skillsets if you seek out different team sizes, company stages, reporting structures, and working environments.
Identifying that variation has been crucial for me as I’ve stared down a lifelong career doing “just writing”. Did I really want that? Thankfully, technical writing doesn’t look the same everywhere, and that variation is what keeps it exciting for me.
In chatting about next steps in a technical writing career with a mentee, we came up with the following list of experiences and job situations that could be on a bucket list for technical writers.
What types of experiences and job situations might make sense on a bucket list look like for technical writers? I’m still developing my own, but I wrote up this list to serve as inspiration:"
#AI#GenerativeAI#LLMs#PromptEngineering#TechnicalWriting#SoftwareDocumentation#Productivity: "Many tech writers have a constant fear that AI will take our jobs. I often think, what I’m doing isn’t rocket science. Any person with some education can do it. And yet, just as engineers struggle to write, tech writers frequently struggle with AI tools. They don’t understand how to use them effectively. Even though “prompt engineering” is often a ridiculed term online, again and again I hear feedback from TWs about AI not being useful to them, or they simply don’t have interest in AI, as if it’s irrelevant to their work. This blows me away. When I can ramp up on a product in an hour and write a user guide in a couple of days, and code a doc publishing script that automates even more tasks, how can AI not be useful? How can it not be essential?
An often repeated saying is that AI tools won’t replace us, we’ll be replaced by those who know how to use AI tools. I feel like this is more and more true. Consider this scenario: You hire a roofer to install a new roof, which mainly involves removing the old shingles and installing new ones. One roofer arrives with a hammer. It will take this roofer 2 weeks to do the job. Another roofer arrives with a pneumatic roofing nailer power tool. It will take this roofer 3 days to do the job. The cost of the first roofer is 4 times that of the second. The output is pretty much the same. Which roofer do you hire?
It’s the same with tech writers. Suppose you have a large project. One tech writer can create the documentation using AI tools in a quarter of the time, while the other will take 75% longer. Which tech writer do you hire?
Fortunately, I think tech writers can learn how to use AI tools as power tools. Especially with more awareness and knowledge about effective prompting techniques, tech writers can become much more productive using AI." https://idratherbewriting.com/blog/ai-is-accelerating-me
How to coordinate a docs release with a product release
You also need to define Git best practices for your team about how to manage those, such as:
Whether to use release branches, or merge pull requests frequently but publishing infrequently.
Whether to use Git rebase or Git merge to maintain Git history in a given branch.
Whether and how to use feature branches and pull requests.
Whether to squash merge pull requests to main.
Even if you manage to define best practices that your team is committed to following, there isn’t a way to force your documentation contributors to adhere to all of these best practices. Due to the lack of enforcement of these best practices, you can easily end up in a situation where writers follow slightly different practices based on what their tools make easy to do."
You have to realize that this is a Trojan horse strategy. Like, you want the docs to be the product, fine. This is what all tech writers want eventually. But be very careful about the product not being, for example, the pipelines or the site you’re gonna render. I mean, that might be part of the product. The product is the docs, right? But you have to enter a software company with Markdown with that mindset. Otherwise it will just turn into something that’s not even a feature, and lose importance.
The value of Markdown is that it allow us to enter with very low friction into worlds that maybe haven’t even thought about docs.”" https://passo.uno/pros-cons-markdown/
Why does that happen? Design and implementation costs evaporate as soon as an API is "finished" and consumers are using it. After that, the only thing that still matters to consumers is that the API behaves as it should. If not, they'll look for ways to fix the challenges they're having, and that's where support comes in.
Unless consumers can get all the information they need from the API documentation. If the API documentation can be the preferred method consumers use to troubleshoot their integrations, then you'll end up spending less on support. There will be less hand-holding required as consumers can fix their issues by themselves." https://apichangelog.substack.com/p/two-ways-to-influence-business-growth
Make API documentation comments easier to write and easier to read in source form by introducing the ability to use Markdown syntax in documentation comments, alongside HTML elements and JavaDoc tags.
Do not adversely affect the interpretation of existing documentation comments.
Extend the Compiler Tree API to enable other tools that analyze documentation comments to handle Markdown content in those comments.
Non-Goals:
It is not a goal to enable automated conversion of existing documentation comments to Markdown syntax."
#TechnicalWriting#SoftwareDocumentation#DITA#CCMS: "Whether we are talking about technology, governments, business, culture, or the environment – we live in a world of constant change. In our field of work, many of us see changes impact our documentation on a weekly, if not daily, basis. To keep pace with these changes and maximize content reuse, it has become standard practice to employ some form of topic-based authoring tool.
However, when technical communication professionals consider their content authoring and management strategies, the best solution is not always clear. Does it require a component content management system (CCMS) based on the Darwin Information Type Architecture (DITA)? Or will a more general solution for topic-based authoring provide the necessary features?"
#TechnicalWriting#DITA#Markdown#SoftwareDocumentation: "Moving from DITA (Darwin Information Typing Architecture) to Markdown for technical documentation involves weighing several benefits and risks, which are pertinent to the specific needs and workflow of technical writers
While Markdown offers notable advantages in terms of productivity, collaboration, and alignment with modern development workflows, it also presents significant challenges in content structure, scalability, and feature richness.
Technical writers must be prepared to navigate the less-structured environment of Markdown and may need to employ additional tools and practices to compensate for the loss of certain key capabilities inherent in DITA’s more complex system.
The decision to transition should therefore be made with a thorough understanding of these trade-offs and an assessment of the specific needs of the documentation project.
#APIs#APIDocumentation#Marketing#SoftwareDocumentation#TechnicalWriting: "So, it looks like API documentation is a form of marketing. It's not traditional marketing but more like one directed at a very specific technical audience. An audience that knows what they want and is very knowledgeable about certain technologies.
The goal of documentation is to help a target audience engage with the API as quickly and easily as possible. By aligning the needs of consumers—using their preferred programming languages and offering SDKs—with the business objectives, documentation is a marketing tool you can use to drive results."
"- Think strategically, as in content strategy. The potential of AI content in certain scenarios, such as integration docs or code samples, is huge. Figure out where AI should interface in your information architecture and let the LLMs roam within the boundaries that you build for them. Shepherd AIs.
Test your assumptions, test everything. It’s already common knowledge that default LLMs’ output is good only up to a certain point, if not outright unusable. Even my kids can tell whether the stories GPT came up with are lame. Stage A/B tests and user research to verify how good LLMs really are.
Embrace metrics and docs observability. Don’t just unleash AI on a product and forget about it; instead, measure the impact of the AI-generated or AI-edited content across your product and content properties, see where they have the greater impact and where they could hurt your product’s credibility.
Hire with AI augmentation in mind. As I explained in Hiring technical writers in a ChatGPT world, writing skills are based on the same pattern matching and retrieval skills that LLMs mimic. Unless you expect writers to work offline on parchments, tolerate a certain degree of AI augmentation.
Advocate for your craft at work. Tech writers only write during a fraction of their time — the rest is spent chasing subject-matter experts, organizing information, and more. Don’t let stakeholders think that the deliverable is your job: Remind them how the cake is actually made."
#APIs#APIDocumentation#Tutorials#TechnicalWriting#SoftwareDocumentation#SoftwareDevelpment: "The best tutorials present information that helps consumers fulfill a use-case scenario that feels real and meaningful. Instead of coming up with a made-up use-case, you can research what are the things your API consumers would want to do. Then, create tutorials that teach how to achieve those results with your API. The goal of the tutorial is to educate readers on how they can use your API—or some of its operations—to get their job done.
So, what are the elements that a good API tutorial should have? Let's look at some of the most important ones:"
#TechnicalWriting#SoftwareDocumentation#SoftwareDevelopment: "Soon after publishing Tips for hiring your first technical writer, some readers kindly suggested to follow up with a post covering the previous step in the tech writing journey, that is, the realization that one needs a technical writer. As there seems to be a strong appetite for this kind of content, I’m going to spend some words to list what I think are the most egregious signs that your team, company, or product requires a technical writer (or a tech writing team).
If you’re here reading this, you might belong to one of two groups: Either you believe that you need technical writers and arguments to defend the need for them in your team or you don’t know what I’m talking about and you’ve been sent to this blog by someone who does care about documentation. Whatever your group, you should be able to recognize the following signs in your workplace or project. If you do, it might be time to consider opening your mind to the possibility of hiring a tech writer.
First though, let me open with a simple premise: If you’re shipping a product and that product is more difficult to use than a kazoo, you need the product to communicate to users through UX writing, docs, or both, and create a team in charge of executing the underlying content strategy. If nobody in there is heeding to the docs hierarchy of needs, that might be due to a lack of docs culture, ruthless focus on other aspects of product development, lack of funding, etc. It’s completely normal, and also sad.
#SoftwareDocumentation#DocsAsTests#DocsAsCode#APIDocumentation#TechnicalWriting#SoftwareTesting#SoftwareDevelopment: "I initially developed and implemented Docs as Tests at Skyflow, a startup that moves fast and releases features and updates even faster than I’d experienced before. I searched for tools to help me manage the pace of changes: there were style linters, API testers, and engineering-focused testing tools, but there wasn’t anything to easily help me validate the product descriptions or procedures in my docs. So I built my own, and Doc Detective was born. Doc Detective is a toolkit that parses docs and runs tests (like stepping through procedures) directly against UIs and APIs. It’s designed so non-engineers can use it individually, but teams can also collaborate. When I set it up to test my docs, it caught issues that I had no idea of. It was a game-changer.
But Doc Detective is just a tool (a good one, I like to think!), and no tool solves every problem. I wanted to find a way to apply my learnings to the broader docs community, and I came up with Docs as Tests—a strategy that can be implemented with whichever tools you choose to validate your docs. I’m excited to share my learnings with you and to learn from you as well."
The specifics may vary from team to team and tool to tool, but this is the broad shape of what this process looks like:
Write docs examples in unit test suites
Excerpt example code for inclusion in docs
Include example code in docs
Run docs tests in CI
In another post, I’ll dive deeper on what your docs code examples and tests should cover. For this topic, I’ll follow a code example from the unit test suite to publishing the docs."
#TechnicalWriting#APIs#APIDocumentation#SoftwareDocumentation: "In this podcast, I chat with Bob Watson about an upcoming API documentation course he'll be teaching at the University of Washington. Bob has extensive experience working as an API technical writer at big tech companies like Microsoft, Amazon, and Google. The UW reached out to Bob to develop this new course offering. The 14-week evening course will cover fundamentals like understanding developer behaviors, working with various types of APIs, publishing workflows, as well as hands-on practice. A key component is having students create API documentation portfolios they can use to demonstrate their skills."
At which point during product usage were docs consumed?
Was the consumption of docs followed by normal operation?
Did docs help in setting up or configuring a feature?
Is increased docs consumption followed by increased product usage?
Which parts of the documentation proved more useful?
Which gaps exist in the documentation that we could document?
Even though all the previous questions could be answered through user research, or less directly through web analytics or A/B testing, a more efficient, less opinionated approach could be to track the journey of the users through the product and the documentation itself, using techniques such as real user monitoring (RUM) and correlating the resulting data with back-end logs, traces, and metrics. Observability solutions already do this for complex journeys such as adding items to the shopping cart of e-commerce sites, for example, so why not tracking docs usage?"
#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."