API Technical Writer AI Tips

All the buzz surrounding API technical writers lately seems to be tinged with fear. Many are apprehensive that AI will soon swoop in and snatch away their jobs, leaving them high and dry in a sea of automated content creation.

But me?

I’m not buying into the doomsday scenario.

Over the past year, I’ve dabbled with AI-powered tools aimed at streamlining technical writing processes. A buddy of mine in the biotech realm out in Silicon Valley? He’s been using AI to churn out articles left and right. Is it cheating? Well, maybe a little. But leveraging AI to generate seed content isn’t all smoke and mirrors. However, my foray into this realm has taught me a thing or two.

Citations can be a real headache. If I’m using AI to do the heavy lifting, can I really claim the content as my own? It’s a gray area, especially in the world of SaaS technical writing where citations often get overlooked.

One tool that caught my eye is Jasper.ai, primarily because of its robust plagiarism detection feature. Style guide integration, though, remains a challenge. Many AI tools I’ve come across struggle with seamlessly integrating company-specific writing style guides, which can be a real dealbreaker for some projects.

Then there’s the issue of use cases.

They’re the lifeblood of solid help documentation, taking users from greenhorn to seasoned pro. But getting them right? That’s been a bit of a struggle in the industry. Enter Copy.ai, a tool I’ve found useful for automating the use case writing format.

However, when dealing with proprietary help docs, there’s always that fine line between speedy production and NDA compliance that we need to tread carefully.

Now, let’s talk about creativity in API technical writing.

It’s a factor that often gets swept under the rug. Many technical writers fail to recognize the importance of crafting documentation that’s not just informative but also engaging and user-friendly. This issue hit home during my stint at Coinbase, where I was tasked with writing onboarding documentation for a 100+ new software engineers.

  • Instead of resorting to the same old song and dance of endless pages cluttered with Confluence links and data tables, I pitched a bold idea.
  • Why not spice things up with visually engaging diagrams infused with color and graphics?
  • Sure, it was a time-consuming endeavor, but the payoff was immense.
  • It completely transformed how newcomers absorbed information about their software stack and APIs at Coinbase.

Check out some examples of my innovative documentation style from my time at Coinbase: pdgseo.com/portfolio. Of course, not every documentation project is a canvas for creativity. But given the labyrinth of onboarding documentation that users have to navigate, finding that balance between textual information and visual aids is crucial.

Images and simplified tables aren’t just eye candy; they’re essential for providing readers with much-needed breaks from dense content, ultimately enhancing comprehension and retention. Achieving this delicate balance requires close collaboration with product managers to ensure that creative approaches align with the project’s overarching vision and goals.

In essence, injecting creativity into API technical writing can yield remarkable results, turning complex documentation into accessible resources that empower users and streamline their learning journey.

Now, onto the topic of docs-as-code. It’s a methodology that’s near and dear to my heart.

I hopped on this bandwagon early in my tech writing career, and let me tell you, it’s been a game-changer. Not every organization is sold on the idea, though. I’ve encountered plenty of technical writer consultants who scoff at the notion of docs-as-code.

But why?

After all, we’re working alongside software engineers day in and day out. Shouldn’t we be working like them too? Sure, there’s a bit of a learning curve involved.

I’ll be the first to admit that diving into the nitty-gritty of code isn’t everyone’s cup of tea. But back in 2017, I took the plunge and built a new static API UI for atdata.com (formerly TowerData.com). It was equal parts exhilarating and terrifying, but the end result was well worth it.

Check out the finished project: docs.towerdata.com. Now, docs-as-code isn’t always the right fit. There are instances where you’re shackled by the constraints of your technology stack, and in those cases, I default to the tried-and-true Confluence for internal dev help docs.

But enough about me. Let’s talk about the users.

Access is the name of the game when it comes to help docs. I’ve had the pleasure of working with several SaaS companies that swear by publishing developer documentation in Confluence. But not all roads lead to Confluence.

Take a client of mine in San Francisco, for example. They were drowning in outdated Confluence pages, thousands of them. It’s a common pitfall fueled by tech debt. Our solution? We went on a pruning spree, axing outdated pages left and right based on user page analytics.

Let’s not forget the importance of readability. Chunking up that wall of text, throwing in a few visual aids, and keeping the jargon to a minimum can work wonders for weary eyes. I’ve found that integrating soft background colors can ease the pain of sifting through complex docs, especially for those marathon sessions.

But formatting errors? They’re the bane of every technical writer’s existence. Picture this: you’re knee-deep in a project with a client like Alchemy.com, and you come face to face with poorly formatted parameter definitions. It’s enough to make you want to pull your hair out.

My approach with Alchemy was to roll up my sleeves and tackle those long parameter definitions head-on. Converting them into formatted tables might sound like a simple task, but trust me, it’s worth its weight in gold. Sure, it takes a bit of time to craft Markdown tables, but the payoff in terms of readability is immense. Plus, once you’ve got the hang of it, reusing Markdown table code becomes second nature.

Formatting isn’t just about making things look pretty; it’s about making them easy to digest. That’s why I’m a stickler for simplicity. Short paragraphs, numbered lists, and bullet points are my bread and butter when it comes to crafting documentation that’s easy on the eyes and brain.

But here’s the thing: formatting isn’t just a one-person job. It requires buy-in from the entire team. At Alchemy, we made it a point to hold weekly meetings to peer-review new content. A quick 30-minute chat twice a week worked wonders for keeping everyone on the same page and ensuring that our documentation maintained a consistent style and tone.

api technical writer

Speaking of consistency, let’s talk about writing style guides.

They’re like the North Star for technical writers, providing clear guidance on everything from voice and tone to formatting and terminology. In my experience, the Google developer doc writing style guide is a Godsend for API documentation. It’s chock-full of simple standards that make managing voice, tone, and formatting a breeze.

But here’s the kicker: not every company has a writing style guide in place. That’s a big mistake. Even small organizations can benefit from having some sort of style guide, whether it’s an existing one from Google or Microsoft or an informal internal guide cobbled together by the team.

Why bother with a style guide, you ask? Simple: consistency. By defining things like how to avoid passive voice or when to use active voice, you’re ensuring that your documentation reads like a well-oiled machine. And let’s face it, nobody wants to wade through a mess of inconsistent writing styles and formatting mishaps.

Another thing many writers overlook is error handling in API documentation. Sure, it’s not the most glamorous part of the job, but it’s essential. Just ask Stripe. They’ve set the gold standard when it comes to documenting API errors, providing users with clear, concise explanations and solutions for when things go awry.

Too many technical writers skimp on error documentation, and it’s a real shame. Sure, it takes time to write up all those error messages and code examples, but it’s time well spent. Robust API documentation isn’t just about showcasing the sunny side of things; it’s about preparing users for the inevitable bumps in the road.

But error handling isn’t the only area where style guide standards can shine. Take HTTP response codes, for example. They’re like the bread and butter of API documentation, yet so many writers overlook them. Integrating them into easy-to-read tables is a no-brainer, and yet so few technical writers take the time to do it right.

If you find yourself stuck with just two columns of content, fear not. There are still ways to make your documentation shine. Consider integrating dropdown widgets for large block content. Most documentation editors offer this feature, and it’s a game-changer when it comes to presenting complex information in a user-friendly format.

api technical writer error codes

Another area where technical writers often struggle is in creating clear and concise error messages. Error messages are an essential part of any API documentation, as they help users understand what went wrong when something goes awry. However, poorly written error messages can be confusing and unhelpful, leaving users frustrated and unable to troubleshoot their issues.

To avoid this problem, I always recommend following a few simple guidelines when writing error messages. First and foremost, error messages should be clear and descriptive, clearly indicating what went wrong and why. They should also be written in plain language that is easy for users to understand, avoiding technical jargon or obscure terminology.

In addition to being clear and concise, error messages should also be actionable, providing users with guidance on how to resolve the issue. This could include suggestions for troubleshooting steps, links to relevant documentation, or instructions on how to contact support for further assistance.

Finally, error messages should be consistent across your documentation, using the same language and formatting conventions to ensure a cohesive user experience. By following these guidelines, you can ensure that your error messages are helpful and informative, rather than frustrating and confusing.

Now, let’s talk about the importance of user feedback in the documentation process. User feedback is an invaluable source of information for technical writers, providing insights into how users are interacting with your documentation and where improvements can be made.

There are many ways to collect user feedback, from surveys and user interviews to analytics tools and feedback forms. Regardless of the method you choose, the key is to listen to your users and take their feedback seriously. This could involve making changes to your documentation based on user suggestions, addressing common pain points or confusion, or simply acknowledging that certain aspects of your documentation could be improved.

In my experience, user feedback has been instrumental in shaping the direction of documentation projects, helping to identify areas for improvement and guiding decision-making processes. By actively soliciting and responding to user feedback, you can ensure that your documentation remains relevant, useful, and user-friendly.

Localization is a critical aspect of technical writing, especially in today’s globalized world where products and services are used by diverse audiences spanning different countries and cultures. Neglecting localization can lead to misunderstandings, frustration, and ultimately, a poor user experience.

When it comes to localizing documentation, there are several key considerations to keep in mind. First and foremost is language. Translating your documentation into the languages spoken by your target audience is essential for ensuring that users can understand and effectively use your product or service.

However, localization goes beyond mere translation. It also involves adapting your documentation to the cultural and linguistic nuances of different regions. This could include using appropriate idioms, examples, and references that resonate with local audiences, as well as ensuring that your documentation complies with local regulations and standards.

For example, consider a software company that is expanding into the Japanese market. In addition to translating their documentation into Japanese, they may also need to adapt their content to reflect the unique preferences and expectations of Japanese users. This could involve using Japanese-specific examples and terminology, as well as ensuring that the documentation aligns with Japanese cultural norms and values.

In addition to language and cultural considerations, localization also involves technical aspects such as date and time formats, units of measurement, and currency symbols. These may vary from one region to another, so it’s important to ensure that your documentation is flexible enough to accommodate these differences.

Furthermore, localization extends beyond the content of your documentation to include the delivery mechanisms and user interfaces through which it is accessed. This could involve providing localized versions of your website or documentation portal, as well as offering support for different input methods and devices commonly used in different regions.

Overall, localization is a complex and multifaceted process that requires careful planning, coordination, and attention to detail. However, the benefits of localization are well worth the investment, as it can significantly enhance the usability, accessibility, and effectiveness of your documentation for users around the world.api technical writer

Now, let’s shift our focus to the role of collaboration in technical writing. Technical writing is rarely a solitary endeavor; instead, it often involves collaboration with various stakeholders, including subject matter experts, product managers, developers, and designers.

Collaboration is essential for technical writers to gather the necessary information, clarify complex concepts, and ensure accuracy and completeness in their documentation. Working closely with subject matter experts (SMEs) allows technical writers to tap into their expertise and knowledge of the product or service being documented.

Effective collaboration with SMEs involves building strong relationships, establishing clear lines of communication, and demonstrating empathy and understanding for their perspectives and priorities. Technical writers must be able to ask the right questions, actively listen to the answers, and translate technical jargon into clear and accessible language for their audience.

In addition to SMEs, technical writers often collaborate with product managers to understand the strategic goals and priorities driving the development of the product or service. This helps them tailor the documentation to align with the overall vision and objectives of the project.

Developers also play a crucial role in the documentation process, as they provide insights into the technical implementation details and functionality of the product or service. Technical writers may attend stand-up meetings, code reviews, and other development-related activities to stay informed and up-to-date on the latest changes and updates.

Designers can also contribute to the documentation process by providing input on the visual layout, formatting, and presentation of the documentation. Collaboration with designers ensures that the documentation is visually engaging, easy to navigate, and consistent with the overall design language and branding of the product or service.

Furthermore, collaboration extends beyond internal stakeholders to include feedback and input from external sources, such as customers, users, and community members. Soliciting feedback from end-users allows technical writers to identify pain points, address common issues, and continuously improve the quality and relevance of their documentation.

Overall, collaboration is a cornerstone of effective technical writing, enabling writers to leverage the collective expertise, insights, and perspectives of various stakeholders to create documentation that is accurate, comprehensive, and user-friendly. By fostering a culture of collaboration, technical writers can maximize the impact and value of their documentation, ultimately enhancing the user experience and driving success for their organization. Contact me if you need an API technical writer.