Sarah Mei and Sarah Fox and some other people and I were talking on Twitter about code school graduates, and how they frequently do really well at mid-level positions because they have communication skills from their previous careers.
Sarah Mei@sarahmei@plaindocs @scribblingfox Yeah, that is super interesting. Thanks for linking it. I guess that's why there's no writing boot camps? đ16:22 PM - 04 Jul 2017
Heidi @LISAConf@wiredferret@sarahmei @plaindocs @scribblingfox Been thinking about why there aren't, and it's because it's hard to promise som⌠twitter.com/i/web/status/8âŚ17:05 PM - 04 Jul 2017
We all agree that teaching someone to write well enough to be a Professional Technical Writer is more than you could cover in a six-week intensive, probably. Depending on where they start. I could absolutely turn a motivated journalist into an entry-level tech writer in 6 weeks. Theyâre 3/4 of the way there already. But most people would need to learn the following from scratch (in no particular order):
- Audience analysis
- Task-based writing
- Procedural writing
- User story writing
- Error writing
- Bug writing
- Conceptual writing
- Diagrams, illustrations, and screen captures
- Rudimentary tools use
- Sentence construction
- Bullet point use
- Theory of simplified English
- Accepting editorial feedback
- Accepting technical feedback
- Elements of information architecture and presentation
- Elements of usability and accessibility
- Style guide use
Even if youâre coming out of a liberal arts/literary background, half of that list is something you may never have heard of. You can construct a great sentence, and you know how to use a semicolon, but your experience to date has rewarded you for things that donât matter at all in technical writing. Youâve gotten good grades for making persuasive arguments or writing pithy literature reviews, but no one in my English Lit classes ever told me that I was addressing the wrong audience or designing my headings badly.
So thatâs a daunting list of things to try to cram to get people into what is, letâs face it, a less glamorous profession than Code Warrior. I happen to think itâs the best and most influential place to be in a development team, but thatâs not what the pay scales say.
That said
That said, I think I could do a LOT with teaching code school students and other developers some really basic writing skills. I tried this out at a Workshop at Write the Docs this year, and it went pretty well. Iâd love to present it elsewhere. Iâm putting the outline below the cut, if youâre interested.
Give me your developers for a day, and Iâll teach them to write a well-constructed error code and a readable bug report and a coherent status email. Give me two days and Iâll teach them about audience and analytics and deletion.
I want to do this for code schools, so we can catch people when they are frantically learning, so they will remember to look it up later. I want to do this for open source projects, because it is so hard to find or hire a technical writer. I want to do this for conferences where junior developers are looking to elevate their game. I have been traveling around to developer conferences for several years now, trying to distill everything I know from 20 years of my career into something that has value for coders, and I am convinced it has value.
Making words
Research basics
- Who am I writing for?
- What do they need to know?
- How can I find that out?
- How can I explain it?
- Who can help me?
- Who can check my work?
Writing basics
- Make your sentences short and impersonal
- Use graphics for concepts, but avoid screencaps
- Use style guides and linters if you can
Using templates to write
- Templates organize your thoughts and keep you from forgetting things
- Templates add a standard look at feel at low mental cost
- More like madlibs than âwritingâ
Organizing words
Every page is page one/search-first writing
- If you donât answer the question, or at least point to it, youâve failed
- People are seldom looking to grasp the whole concept
- Search terms are precious goldÂ
Indexing and search
- All the words present are indexed
- None of the words missing are, unless you make an effort
- We donât all use the same words for things, especially in technology
Semantic tagging and re-use
- Semantic text is separating the content from the form
- Semantic tagging attaches labels to little bits of content â text objects
- Reuse means that you donât have to make the same change dozens of times
- Reuse also means that there is overhead inherent in your documents. You have to compile.
Sorting topics into buckets
- Even with search, you need to have some kind of structure
- Group things together by how and when the user experiences them, not programming
- Putting like things together lets people find what they actually want
Links, menus, and flow
- Give people a next step
- Provide related information links on the same page
- Tell them where they are in the document with breadcrumbs
- People think of things differently. Some people have to understand relationships
Distributing words
Static sites
- Easy to get
- Easy to maintain
- Limited control
Hosted sites
- Someone else sweats the hosting
- More control over access by users
- Less control over access by you
Baked in to your product site
- All the worst features of both
CMS/Knowledge base articles
- Useful for a community that knows what it wants
- Prone to aging out
- Sometimes diverges from published docs
Professional writing tools
- So shiny and powerful
- Learning curve like a brick wall
- Seriously, itâs an IDE
- Multi-client single source, variables and wacky stuff
Paper-ish things
- Essential for some things
- Reassuring to some people
- Touch is a sense we can bond to
Using templates to publish
- Unified look and feel
- Consistency
Collaborating on words
Using templates as an invitation
- Less scary than a blank page
- Sets expectations
- Encourages multiple writers
My one weird trick
- Write what I think
- People love to tell you youâre wrong
How to structure a hack day
- Set a goal of things to delete
- Set a goal of things to fix
- Keep track of things you donât have time to handle today
Deleting words
Why to delete
- Old stuff is wrong and terrible
- Wrong stuff hides the right stuff
- Antiwords leave space for people to learn and think
How to delete
- Temporarily
- Based on analytics
- Ruthlessly
This post was originally published on heidiwaterhouse.com