Hacking the English LanguageΒΆ
| Authors: | Nina Vyedin |
|---|---|
| Time: | 12:00 - 12:20 |
| Session: | http://docs.writethedocs.org/2014/na/talks/#nina-vyedin-hacking-the-english-language |
| Link: |
Or, what can we learn about writing from our programmer friends.
When Vyedin was in college, she did really well on her first paper. And when she went to write the second, she blocked at the blank page. Now she works for Xamarin, and when you create a new app using their tool, you get boilerplate and guidance about what to do next. What if you didn’t have to start with a blank page when you’re starting a document?
Don’t start with a blank page.
Create a template for each type of document you write, and put them in the same place, so you never have to start with a blank page.
Make a spec
While mentoring a new writer through a document, Nina realized that she and the new writer thought the document was answering different questions. So you can write a simple spec for your doc, that keeps everyone involved on the same page.
- What question is this document meant to answer?
- Who is the target audience?
- What’s the current state of the documentation on this topic?
- What’s the work plan?
Programmers also have design patterns: pre-established architectural patterns for software. Documentarians have that, too, and you can use those to make the work easier.
Writing for Clarity: Name your variables
Most programming texts contain a section on naming variables. Writing needs this, too. There are things like the undefined “if”, a lack of ownership (passive voice), vague terms (“view”, “component”, etc), or ideas whose name changes over time, all of which make your writing less clear. Be specific, and be precise.
Editing
Editing isn’t just about correcting spelling or punctuation. Editing is the refactoring of writing. Editing should be about rearranging, restructing, and clarifying what’s going on in a document. (Just make sure you’re not changing the question.) You don’t have to be an expert to be a good editor (although it helps); you just need to be willing to ask questions.