# Content Best Practices

## Write as *you* not as a representative

Core to the principles of OpenSearch is open source. Open source is inherently about people and collaboration that goes across organizational lines. This extends to how content is written for [opensearch.org](https://opensearch.org/). Just as code ultimately is attributable to an individual’s GitHub account, blog posts should be attributed to people not organizations or teams. If multiple people collaborated on a post, attribute it to all those people. 

Being crisp with how you reference yourself and work is important as well. Generally, collective pronouns (words such as *our*, *we*, *us*) can be confusing and lead readers to make assumptions about who belongs in that collective group. When proofreading, actively scan for these words and ask yourself if the reader will unambiguously understand whom your are talking about: if there is any doubt, rephrase. It’s typically easier to write in the first (*I*) and second person (*you*) from the start rather than trying to revise content later. If multiple people are collaborating on a piece of content, use collective pronouns sparingly, but make sure it’s very clear that every instance actually refers to the collective of the authors of the content not some other group.

## Empathy for readers

The best content has empathy for those reading it. The audience for your content will be wider than you might imagine - folks that have little experience with this type of software and those who have tons, people that share you’re cultural background and those that don’t, users on powerful laptops with unlimited bandwidth and those who have limited bandwidth on a phone, those who are interested in how the software is written and those who only want to use and install it.  Given that, thinking about how your content will make people feel as well as what conclusions will be drawn from your writing will lead to more accessible and useful communication.

Writing for various skill levels is tricky, but achievable. There is no problem with keeping the technical level high but make sure you provide pathways for those who may need extra background: **links to other content that explains foundational concepts are always welcome** as are short, inline, high-level explanations. Another good tip is to **avoid the use of “simply”** or related words; James Fisher has a great write up on why using (or implying[) ‘simple’ has the counterintuitive effect of insulting your reader](https://jameshfisher.com/2017/02/22/dont-use-simply/). 

Every reader comes with their own multi-layered cultural background. Given that OpenSearch is a world-wide project, **relying on specific cultural references is a challenging proposition**. Referencing culture may be unavoidable, but consider the value of the cultural reference *and* also having to explain the cultural reference to those who might not understand it. If your reference is a cornerstone of your story, then it might be worth explaining (and over explaining to those who understand the reference) but if that added weight is worth it, go for it. If not, consider revising.

Sometimes a picture is worth a thousand words - content is almost always reinforced by a good diagram or screen shot. It’s important to keep in mind that reinforced and replaced are not the same thing. **Relying on a reader to see a picture or animation to convey your message is a poor strategy** - users may not see or understand the image the same way as you do. Images and especially animations can add considerable bandwidth burden for users - so **those on phones or limited connections can be negatively impacted by large files embedded in the content**. Viewing a screen shot from a desktop UI also is a poor experience for readers on phones or tablets.

It’s easy to get fixated on open source as a strategy for building software but it is, in equal measure, also about how the software can be used and distributed. The beauty of open source software is that the line between the builder of the software and those using the software is not sharply defined. Someone who uses the software daily can make a small change easily. **Good content balances the contributor audience with the user audience in a way that doesn’t create artificial distinctions and can tell stories that appeal to both those who primarily fall in either camp.**

## Revise and Proof

Writing is a process, not a task. Very few pieces of content will go directly from your mind to being published. It’s usually best to focus on content first then fully read through the content a couple of times (reading it out loud or using a screen reader is a helpful process for many writers). When submitting content to opensearch.org, it’s expected that you’ve already proofed the content in situ by [building the website locally](https://github.com/opensearch-project/project-website#building-the-website) so you can see if your content makes sense in context. The website team will be doing the same thing to ensure published quality.

The other thing to keep in mind is that content on a website isn’t immutable. If you find an issue after you publish, a new pull request can fix that issue. So, while everyone wants to publish the perfect blog post the first time, making changes later is possible. If there are substantial changes to a piece of content after publishing, it’s good to indicate to the reader that the content was revised and for what reason. If someone points out a factual mistake, make the change and own up to the mistake and thank the person who made the content better.