API Documentation - #02

Highlights: Free technical writing courses, Communicating warning information in HTTP APIs, How to manage documentation as code.

Technical Writing

🎓Free technical writing courses - Google released an education platform to train engineers on technical writing. The portal comes with two modules to learn about planning and authoring technical documents.

📝How to develop a combined content audit and plan - Debra Kahn wrote a guide for recognizing which content from a website needs improvement and how to frame the next actions in a spreadsheet.

📝 Using numbers in technical documents - ClickHelp shared a set of ground rules and tips for using numbers in user manuals.

Developer Experience

📹 Communicating warning information in HTTP APIs - Andre Cedik summarizes how well-known APIs are returning errors. To make "soft error handling" easier for future API development, he also proposes a draft RFC for communicating warning information in HTTP APIs.

📝 REST API: Sorting, filtering, and pagination - Tania Rascia documented how to create pagination, filtering, and sorting endpoints. The article highlights the key points to take into account when designing an API.

📹  The augmented API design reviewer - Arnaud Lauret showcased how to enforce API Design guidelines using the OpenAPI Specification and Spectral, a JSON/YAML linter.

Docs as Code

🐦How to manage documentation as code - David Garcia proposed a basic workflow to start treating documentation as code in just ten tweets.

📝 GitHub CLI 1.0 is now available - GitHub released the 1.0 version of their CLI. The command-line tool allows you to run your entire GitHub workflow from the terminal, from issues to releases.