Latest update in the docs consolidation project: a page that has only 1 section/example in some of our less complete docs sets is up to 5 sections/24 subsections in the consolidated page.
The page is now so long and comprehensive that you have to scroll the “On This Page” table of contents in the sidebar.
We’ve decided that’s too long and will split it into a few pages. But this project is already yielding great results by increasing the comprehensiveness of our docs.
#TechnicalWriting folks of Mastodon!! At my New Job I have to select a tool for redoing and managing our docs in a structured way. These include manuals and datasheets (Web and PDF), and contextual help, so content reuse is important.
I'm completely in over my head as the only writer. I've never managed doc projects nor used specialized documentation tools, having worked mostly in HTML/MD formats and Word files for customers, so have not been involved in publishing them.
#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#APIs#APIDocumentation#AsynchronousAPIs#AsyncAPI#EventDrivenAPIs#ApacheAvro#JSON: "Luckily there's a specification similar to OpenAPI but directed at defining event-driven APIs. I'm talking about AsyncAPI. It's a specification that lets you define an API that's asynchronous in nature. By using AsyncAPI you can define, among other things, the different topics where events will be dropped, and the shape of the messages that represent each topic.
And this is where things get interesting. The shape of messages or, in other words, its payload, can adhere to specific standards. Without messages, there's no way to communicate events. And, following standards helps to guarantee the correct publishing, transport, and consumption of messages. If messages don't follow any standards, it's hard for developers to understand the shape of the messages. In addition, it's easy for consumers to stop working because, suddenly, messages are being shared in a slightly different format.
Among different message standards, there's one particularly interesting to me. Apache Avro isn't just a theoretical standard. It's also a serialization format. You can say it's a competitor to JSON but specialized in working with event-driven APIs. In the same way you can use JSON Schema to define the shape of JSON data you have Avro Schema to help you specify what Avro message payloads look like."
Come to the #TechnicalWriting meetup I am running in #Melbourne this Thursday and learn about Lego Docs! Lego Docs is an activity I invented that you can run with developers/engineers to help them develop their technical writing skills. It is fun and helps participants identify crucial elements in a well-written document.
I am looking forward to running a meetup in #Melbourne next Thursday for technical writers and anyone involved in IT work. In it I will explore some fun activities that you can run with teams of engineers to help them improve their writing skills.
There's lego and games involved.
There is still space for you to come. We also would like to hear your ideas and experience in running activities to help people improve their writing skills.
#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#DITA#XML#DITAXML#Documentation#InformationArchitecture#StructuredAuthoring: "DITA is defined in its specification as “an XML-based architecture for authoring, producing, and delivering topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways”. Originally developed by IBM in the early 2000s, DITA stands for Darwin Information Typing Architecture. “Darwin” refers to the naturalist Charles Darwin and his theory of evolution, reflecting DITA’s principles of specialization, inheritance, and adaptation.
DITA topics are standalone, context-free blocks of content, with content types kept clearly separate. There are three main topic types in DITA, all of which are inherited from the base topic type <topic>:
<concept>: background information that users must know before using the product
<task>: step-by-step instructions that users need to perform a task
<reference>: product specifications, commands, or other reference material
You create a document by selecting which existing topics should be reused and referencing them in what’s called a DITA map (similar to a table of contents).
Being an open standard, DITA has no proprietary restrictions. But while you’re not forced to buy a specific tool to use it, commercial XML editors have many features, such as visual editing and validation, that make writing DITA content much easier."
#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."
🧵 I have lots of respect for the developers of Textual, so this is friendly, constructive criticism
I feel like the UX of this app could be greatly improved by incorporating some #technicalwriting practices, as well as some things I have learned working in tech for the last few years
First off, when you try to connect to a server and mess the URL up somehow, it gives no feedback on what it doesn't like about your input. So I have no idea what I need to fix
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/
New article published, "Exploring static web in the digital humanities classroom: the learn-static initiative"
(Coming out only a couple of years after I wrote it!)
@evanwill Thank you so much for sharing this article you and Olivia wrote! I am a technical writer who learned a lot of digital skills through #DigitalHumanities when I was previously working as a professional historian.
These skills that you are teaching are such valuable skills for students to add to their resumes and are foundational for many careers. Digital Humanities give their students communication skills, research skills and foundational technical skills that businesses need. Businesses don't realise this.
I am currently training a couple of people at work in introductory command line skills and git skills. I am looking forward to exploring any curriculum materials you make available online to see if I can draw on them for my tutorials.
In today's fun with API docs, I started a new project using GitHub's GraphQL API. Again.
This time I'm mucking with Issues. Issues have participants. Participants is a UserConnection! - fine, a bunch of other fields have this type so I know it.
But the definition is:
"A list of Users that are participating in the Issue conversation.”
So... what does “participating" mean? People who leave comments? What about reactions, do they count? Is the issue author a participant?
#TechnicalWriting#LLMs#AI#GenerativeAI#DevRel#UXWriting: "In 2024 we’re still rewarding docs sites and focusing our efforts on getting docs up and running, as if we were creating primitive unicellular organisms for the first time. We can and will do better than this. The next stage of the tech writing’s evolution is to integrate with the bigger product lifeform, a step that will finally allow us to leverage things like true docs observability instead of flailing at useless performance metrics. Whether to hire a technical communications specialist will no longer be a question, as it’s no longer a question to have soundtracks in films.
It doesn’t really matter how technical or complex a software product will be. Documentation as a behavior of software components will consistently happen in CLIs, GUIs, developer tools, APIs, and other aspects of software. Wherever there’ll be points of connection between humans and software, there’ll be a need for meaningful, helpful words. If becoming a tech therapist requires merging technical writing with DevRel, the docs are everywhere paradigm will require tech writers and UX writers to merge into a unified professional role, the product writer." https://passo.uno/tech-writing-predictions-2049/
Is it legitimate to write in a #manual for a piece of equipment (that improper use of could lead to damage, injury or death):
If you find yourself asking 'should I be doing this?' the answer will always be 'No'.
?
Seriously I'm running out of ways to say:
don't sit on it, swing from it, stand under it, hold onto it, put your genitals in it, lick it, fart around it, taunt it, make it watch Hayao Miyazaki movies (although it would like them), or feed it pie after dark.
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."