Grammatical correctness is important but it is not everything @alicebartlett Its, it’s, there, their, they’re. It’s easy to get hung up on apostrophe usage or spelling but there are more important things to focus on
@alicebartlett These minor errors can be a distraction from thinking further about the words you’ve chosen and how well they're communicating your thoughts and intent
@alicebartlett Ideally your words would be good and your grammar would be flawless. But grammar won’t save you if the communication of your idea is poor in other ways
Don’t bury the lede @alicebartlett Put the most important information at the top of the section. Don’t make people read a whole paragraph to understand the most important part
@alicebartlett How do I raise a ticket? // information on how to raise a ticket Raise a ticket in Jira // information on how to raise a ticket // Better // OK
@alicebartlett Be conversational It’s OK to use contractions like “there’s” instead of “there is”. Our documentation can be useful without being formal.
@alicebartlett I’ve made a mistake by monkeys We’ll email you by monkeys We’ve decided by monkeys A mistake was made by monkeys You will be emailed by monkeys A decision has been made by monkeys
“Simply” adds no value to this sentence. If you don’t know how to rotate the key, it makes you feel bad. If you do, then you don’t need to know it’s simple @alicebartlett