Write Great Tech Content

Write Great Tech Content Lorna Mitchell, Redocly @redocly ~ @lornajane ~ @lornajane@indieweb.social

Communicate technical concepts to a specific audience with a goal in mind @redocly ~ @lornajane ~ @lornajane@indieweb.social

This Talk is About You Great tech content is the best content you can write. •write efficiently •write quickly •write painlessly @redocly ~ @lornajane ~ @lornajane@indieweb.social

Content Types The audience, and the goal. @redocly ~ @lornajane ~ @lornajane@indieweb.social

Readme •What does this project do? Who is it for? •Installation •Usage •Where to learn more, get help •How to interact with the project @redocly ~ @lornajane ~ @lornajane@indieweb.social

Tutorial Non-trivial project: 1.5-3.5k words •Introduction of what the reader will learn •Sequential tasks, minimum context switches •No choices! One way to do each step •Link to supporting content •Result is a standalone thing @redocly ~ @lornajane ~ @lornajane@indieweb.social

Blog post Entertain and inform, 500-1500 words •Showcase a feature or tool •Inspire with a story or use case •Educate (with silly examples) May use a “chattier” tone @redocly ~ @lornajane ~ @lornajane@indieweb.social

Structure 1.Outline the piece 2.Make sure there’s a punchline 3.Remove the history section @redocly ~ @lornajane ~ @lornajane@indieweb.social

Page furniture Create landmarks to make the page easier to navigate. @redocly ~ @lornajane ~ @lornajane@indieweb.social

Code Snippets Always expect users to copy and paste! <?php $email = ‘name@example.com’; $domain = strstr($email, ‘@’); echo $domain; // prints @example.com Clear variable names and comments can help. @redocly ~ @lornajane ~ @lornajane@indieweb.social

Writing process @redocly ~ @lornajane ~ @lornajane@indieweb.social

Writing process The finish is in the preparation •Know the audience and goal •Create an outline •Show up and ship it @redocly ~ @lornajane ~ @lornajane@indieweb.social

Write Great Tech Content @redocly ~ @lornajane ~ @lornajane@indieweb.social

Resources •https://lornajane.net •https://redocly.com •https://diataxis.fr •https://www.thegooddocsproject.dev/ @redocly ~ @lornajane ~ @lornajane@indieweb.social