The conversation also highlights how curiosity drives the development of technical skills, drawing a parallel between the technical writer’s mindset and the logic required for scripting and automation.
Highlights:
Advice for new technical writers starting with API documentation.
Collaboration strategies with developers, emphasizing the need to be sensitive to company and cultural dynamics.
Team structuring and the segregation of duties, noting the value of both highly technical and less technical roles.
Challenges specific to technical documentation in a highly regulated industry like payments.
A deep dive into CLI tools, including how to get started with the terminal, essential commands, and examples of automating documentation workflows (like card generation and file mapping) using the CLI and AI tools (Claude and ChatGPT).
About Casey
Casey has over seven years of experience, including work at Salesforce. She is currently working at Payabli. Her expertise covers documentation and information architecture. She currently manages a team, handling information architecture, developer tooling, and developer enablement. She has experience setting up a “docs as code” workflow and previously worked on one of Salesforce’s email marketing products.
Actionable Takeaways
Be Curious: Embrace curiosity and a willingness to try things and “look stupid” to develop technical skills.
Start API Docs with a Course: Tom Johnson’s Documenting APIs course is highly recommended and free for beginners.
Be the API Expert: Know more about your company’s APIs and how they work together than anyone else, including the engineers.
Know Your Audience (and Culture): Apply the “golden rule of tech writing” (know your audience) to your engineering collaborators by being sensitive to company and cultural differences.
Start with Terminal Navigation: Begin learning CLI by mastering directory navigation commands like
cdandpwd(print working directory).Learn Essential CLI Commands: Utilize
grep(for searching in large repositories),find(for locating files by name), and counting tools (for files, words, or characters).Automate Repeatable Tasks: If you constantly “groan” about a repeatable task, it can likely be scripted and automated using the CLI.
Build CLI Tools with AI: Use AI tools like Claude or ChatGPT to write scripts or bundle existing scripts into a usable CLI tool, leveraging your technical writing skills for clear, logical prompts.
Stay Relevant with AI: Embrace AI for automating boring, manual tasks to free up time for high-value, creative work. Don’t be “grumpy” about new tools.
Ready to level up your docs as code workflow with built-in AI assistance?
Chapters:
0:00 – Introduction of Casey Smith, her experience, and the topic of CLI tools.
0:59 – Casey’s journey in technical writing and developing the “technical aspect.”
1:22 – Casey’s background: from Waffle House waitress to early exposure to APIs.
2:03 – Landing her first tech job at Salesforce and building technical skills (e.g., XML templates for print manuals).
3:35 – Advice on how to get started with API documentation.
3:58 – Recommendation: Tom Johnson’s Documenting APIs course.
4:32 – Key cautions when documenting APIs (e.g., avoid publishing internal endpoints, know the product deeply).
5:48 – Collaboration with developers and adapting to company/culture differences.
8:50 – Structuring a documentation team and dividing responsibilities.
10:50 – How her current team splits tasks (manager handles API definitions; writer handles SDKs/example apps).
12:20 – Different models for documentation ownership (by feature sets, entire product, dev-facing vs. customer-facing).
13:04 – Challenges in regulated finance/payments (money laundering laws, high stakes).
15:50 – Casey’s CLI experience, preference for the terminal, and origins of her scripting habit.
18:52 – How new technical writers can start using the command line.
19:19 – Beginner commands: cd, pwd, grep, find, counting tools.
22:29 – CLI tools she uses: Git commands, Fern CLI for validation, Veil for linting.
22:50 – Overview of Fern (hosted documentation site tool).
23:44 – Use of Veil (Prosaware syntax linter) for guides and API field descriptions.
25:32 – Examples of internal tooling: card-generation pipeline using front matter for components/snippets.
29:20 – Generic CLI use case: mapping markdown filenames to URL slugs.
31:39 – Building new CLI tools with AI (Claude and ChatGPT).
33:53 – How to start creating a CLI tool: begin with a simple script, then bundle multiple scripts.
35:54 – Technical writers’ advantage in using AI due to strong logic/pseudo-code skills.
37:03 – Organizing files and using the terminal for fast navigation (e.g., find in large repos).
39:19 – Advice for tech writers: skill development, automation with AI, staying relevant.
43:01 – What Casey hates (progress meetings) and loves (API definitions, especially OpenAPI).
44:56 – Blog details: docsgoblin.com, where she shares CLI content and a cheat sheet for beginners.
Resources Mentioned
Tom Johnson’s “Documenting APIs” course
CLI Commands:
cd(navigate directories)pwd(print working directory)grep(search text)find(find files)
Fern (hosted documentation site tool and CLI for validation)
Vale (prosaware syntax linter)
The Write the Docs Slack (specifically the “test the docs” channel and the AI channel)
Claude AI (for scripting and building CLI tools)
ChatGPT (for building CLI tools)
Commander (tool for creating CLIs)
The Global English Style Guide (recommended book for good writing principles)
Casey Smith’s blog: docsgoblin.com
