One way to get started with an open source community is to write about it. You can contribute to technical documentation, share how you use the software, or write an article for Opensource.com. But getting started writing is easier said than done. The two most common excuses I hear for not writing are: "I have nothing new to say" and "I'm not a good writer." I'm here to dispel both of those myths.
What should you write about?
"Hunt for the stories that often get left out."
—Erik Larson
For some people, the biggest hurdle to writing is generating an idea or topic to write about. It's common to fall into the trap of thinking, "This topic has been written about, so why bother."
I'm not the first person to write an article on writing, and I won't be the last. What I bring is my unique perspective and things I've learned over the years. I've had people ask me for tips on getting started or how to get better at writing. I decided to turn those suggestions into an article.
Your writing is a reflection of you. Nobody will tell the story the way you do. Your experiences and perspective may be just what somebody else needs.
Here are some prompts to help you come up with a topic:
- What is something you've recently learned? Write about how you learned, what you learned, or what surprised you.
- What questions are you frequently asked? Write up the answer.
- Did you recently search for a how-to article and weren't satisfied with any of the top search results? Write the article you were looking for.
- Did you attend a conference or workshop? Write a post-event summary of what you learned.
- Did you start using a new tool? Write up a how-to or getting-started guide.
What type of article are you writing?
There are different types of writing, including:
- Technical documentation
- How-to guide
- Blog
- White paper or eBook
- Retrospective
The type of content will influence your writing style and tone of voice. A blog is more informal and conversational. Technical documentation is more formal and instructional.
Who are you writing for?
Each piece of writing should have a single audience. The audience is the type of person you are writing for. Before you begin writing, it helps to jot down a few characteristics of your reader. It's important to consider who you are writing for, as well as who you aren't writing for—identifying your target audience will shape what to include and what not to include.
For example, this is who I envisioned when writing this article:
- Has basic knowledge of writing and grammar
- Is interested in improving writing skills
- Works in technology as a developer, sales engineer, customer success manager, or similar role
- Is not an experienced or advanced writer, may have a couple of published articles on a personal or work blog, and wants to write more
- Is writing non-fiction
If you have content for multiple audiences, consider breaking it down into different pieces for the different audiences. Some areas to consider in your audience:
- Level of expertise: novice, intermediate, advanced
- Role: manager, individual contributor
- Goals: why are they reading?
Words matter
The words you choose will have an impact on the reader. Difficult words can make an article harder to understand. Unfamiliar words can make the reader feel stupid. Certain words can accidentally offend a reader. Your goal as a writer is to avoid all of these. Here's how.
Use everyday language
Don't write as a way to show off your vocabulary or the words you've learned from your "Word of the Day" calendar. Write so a reader can understand. There is a reading level associated with every piece of writing. If you're writing technical documentation, aim for about an eighth-grade reading level. This doesn't imply your audience has only an eighth-grade education. It means your writing will be more easily understood. Do you want people to get hung up on the language, or do you want them to walk away feeling like they learned something? Just because you can use big, complicated words doesn't mean you should. Using simple language does not necessarily mean your article will be boring.
Use tools like Hemingway App to check the readability of your writing (it's not open source, but it's excellent). For example, after the first draft, this article was assessed at a fifth-grade reading level. Hemingway also provides suggestions on how to improve your writing—identifying hard-to-read sentences or places to alter word choice.
If you're struggling with coming up with alternative words, check out the suggestions at the Plain English Campaign or the crowdsourced suggestions at Power Thesaurus.
Know which words to avoid
"Substitute 'damn' every time you're inclined to write 'very'; your editor will delete it and the writing will be just as it should be."
—Mark Twain
When writing a tutorial or how-to guide, here are some words to avoid, including "simple," "easy," and "just." You, an expert on the topic you're writing about, may find things easy after years of practice. A beginner may not find things simple or easy. Your readers may get frustrated because they don't find the process or explanation simple.
Have you ever had to reread a sentence or paragraph multiple times because you couldn't figure out what the writer was saying? Have you ever given up on an article because it wasn't making sense to you? I have.
As a writer, do you want your readers to feel confused or unintelligent? I hope not.
Other words to avoid in your writing:
- That
- Really
- Very
- So
- In order to
Generally, these words can be deleted without changing the meaning of a sentence.
After I finish writing, I search a document for instances of those words. When I searched through this document, I found the following sentence:
"This doesn't imply that your audience only has an eighth-grade education, it means that your writing will be more easily understood."
Two instances of "that" appear in this sentence. They're not adding value to the sentence. They can be deleted without changing its meaning. Removing those instances shortens the sentence, and shorter sentences are easier to understand. And speaking of shorter sentences, I also re-wrote it as two sentences.
"This doesn't imply your audience has only an eighth-grade education. It means your writing will be more easily understood."
Use inclusive language
The historical context of words and phrases can lead to people feeling excluded or offended. When writing, you want to make the reader feel included. When you use inclusive language, it makes your reader feel understood, respected, and like they belong. I refer to this guide on using inclusive language from Buffer.
Revising and editing
"Almost all good writing begins with terrible first efforts. You need to start somewhere."
—Anne Lamott
Writing is an iterative process. If you think writers sit down at their desk and, within an hour, have a completed article ready to be published, think again. Some articles take me weeks to complete. Here's a standard process for me:
- Write a rough first draft. By rough, I mean rough. I write without worrying about grammar. The idea is to get words out of my head and onto paper. This step can take anywhere from an hour to a couple of weeks.
- Put the draft away for some time. This can be anywhere from a couple of hours to a couple of days, depending on the publishing timeline.
- Review the draft. Make tweaks and edits.
- Ask for feedback, either from a coworker or a friend. During this phase of feedback, I focus on clarity. Does everything make sense? Is anything confusing, any missing sections?
- Incorporate feedback. No matter how experienced you are at writing, other writers reviewing your work will make it better.
At this stage, I have a pretty solid draft. Now comes my least favorite part of writing—editing. The Hemingway App I mentioned earlier not only tells you the reading level but also provides suggestions to improve your writing. I also use Grammarly to help with grammar edits. For open source alternatives to Grammarly, check out Language Tool or this article on open source writing tools.
One of my writing challenges is using commas appropriately. Grammarly helps me figure out where I miss or misuse a comma. Grammarly identified 43 issues related to the correctness of this article's final draft. The majority were comma errors.
(Dawn Parzych, CC BY-SA 4.0)
In addition to grammatical errors, the app also provides suggestions to help with clarity, engagement, and delivery (some of these features may not be available in the free version). This includes things like word choice and using active vs. passive voice. Some suggestions I accept; others I reject. After reviewing all the alerts and suggestions, Grammarly reports back across all dimensions.
(Dawn Parzych, CC BY-SA 4.0)
Don't be afraid to ask for help with your writing. Behind every good writer is a good editor or a good editing app.
Style guides
Style guides provide standards for improving communication in writing. They include aspects such as punctuation, grammar, and word usage. If writing a document for your company, check to see if it uses a style guide. If it doesn't have a style guide, or if you're writing for yourself, here are some common style guides to follow:
- Chicago Manual of Style
- Google Developer Documentation Guide
- Microsoft Writing Style Guide
- AP Stylebook
Writing is a way to share your thoughts and knowledge with the community. The only way to get started writing is to start typing. Use these suggestions to fine-tune your writing.
2 Comments