Kirby's Sonja Broda on Proofreading
“I rely on a good night’s sleep to put some distance between me and my text.”
Writing doesn't start when you put pen to paper. It starts back in the lab, where you research and find out what works, documenting your progress along the way. Then it's pen to paper to tell others how to do the same thing in the future.
That's how Sonja Broda approaches writing about Kirby CMS, first finding new ways to accomplish things in Kirby then writing them to share the recipes with others. And along the way, software and sleep help ensure the tutorials are ready for those who need them.
Here's Sonja on her writing and editing workflow:
What's your favorite thing you've written recently?
There’s not really one piece I can single out, but what I really like to write are what we call cookbook recipes in our documentation. Single topic tutorials can be anything from just very short helpful quick tips to extensive tutorials that cover a more complex topic in-depth and step-by-step. The ones I like most are the ones that I have to research and that give me an opportunity to extend my knowledge, while at the same time making it available to our users.
What's your standard writing workflow?
I used to keep a list of ideas in spreadsheets in the past, but recently I’ve changed my workflow. Now, whenever I come across a topic that seems interesting or useful for our audience or that I recognize as missing, I quickly create a new subfolder in my ideas folder on the command line. The name of such a subfolder carries the idea. If I have links or notes I want to store or already have an outline, I simply add a text file inside this folder. So whenever I have time or feel like writing, I turn to this ideas folder and pick a topic. This folder is then moved into our getkirby.com repo and I can start writing. For the typical How-to tutorial, I usually create a test case in a Kirby StarterKit, to check if it works as described and to rule out any errors. When I consider it ready, I make a commit, push to our repo and create a merge request.
What's your favorite way to proofread writing and spot things to change?
Especially for the more complex topics, that’s an ongoing process of writing, testing, improving, making sure that changes I make at one point (e.g. renaming plugin names or variables) are changed throughout the text, and finally cross-checking.
For typo fixing, I currently rely on "Language tool" and a good night’s sleep to put some distance between me and my text. But automatic tools don’t catch everything, and once you know your text, you only see what you want to see. So that’s the point at which feedback from the team is needed, not only to fix any remaining typos and wording but also to review the code examples and make suggestions for improvement.
What do you do with the things you cut?
If there is anything to cut that might be stuff for further writing, it goes back in the ideas folder. When a complete recipe isn't accepted, this is mainly because the required workflow was too cumbersome. This has happened a few times and then resulted in the underlying code being improved in a way that the tutorial wasn’t needed anymore and ended up in the trash.
→ Check out Sonja's Kirby recipes, and follow her on Twitter @texnixe.