[[writing-simple]]
== Writing tips

Follow these tips to write your documents well.

[[simple-concise]]
=== Write simply and concisely

Keep your writing as simple as possible.

* Use as few words as possible without sounding too formal or too casual.
* Shorten or simplify long sentences or else break them into separate sentences.
* Use lists to make the content more scannable.

[[international-audience]]
=== Write for an international audience

When you write, keep your international audience in mind.

* Use concepts consistently. Check the glossary for common terms and definitions.
* Avoid words that end in "ing". Words that end in "ing" can be a verb, adjective, or noun. Rewriting your sentence to avoid "ing" is best. So Rewrite your sentence to avoid "ing".

[[accessibility]]
=== Write for accessibility

Imagine how your doc sounds with a screen reader. Are your visual elements described? Do your tables make sense?

=== Write in the active voice

Use the active voice as much as possible.

When writing for highly technical audiences, strictly adhering to the use of active voice can result in convoluted sentences. As a result, while attempting to use active voice can result in improved clarity, contributors can choose to make use of passive voice. That said, we still encourage RISC-V contributors make use of active voice as much as possible.

Here are some writing guidelines:

* Organize information according to a pattern that supports one of both of the following:
	** Phases of development from idea through development, testing, and deployment.
	** Concepts, supporting a learning process, from simple and easy to complex and difficult.
	** Prioritize documenting information that all users require.
	** If possible, illustrate decisions that users must make with examples that show potential outcomes.
* As much as possible, maintain parallelism with respect to how you handle information.

[[style-guidelines]]
=== Develop style guidelines only as needed

I have a list of existing guides that we can use as a starting point. These are likely the most pertinent existing style guidelines that were created for addressing the needs of highly technical audiences as opposed to consumer end user audiences:

* https://www.writethedocs.org/guide/writing/style-guides/[Write the Docs style guide]
* https://developers.google.com/style[Google's developer docs style guide]
* https://stylepedia.net/style/[Stylepedia]
* https://docs.netapp.com/us-en/contribute/style.html#write-conversationally[NetApp styke guide]
