Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Join our discussions of documentation issues here on the blog and on Slack.
Technical terms can vary from everyday words like net, bit, cloud, virus to proprietary terms such as processor, URL, website, bandwidth, that are specific to technical concepts. Many technical terms are portmanteau words – words that result from blending two or more words such as WiFi, favicon, email, freeware, and webinar. Some technical terms do become widely used and understood, but before that happens, they might be hard to understand for people who aren’t familiar with them. In general, be watchful while using technical terms, so that they’re only used while unmistakably communicating your message.
Use common and simple technical terms that can be understood by the majority of readers.
Don’t create a new term if an existing term serves its exact purpose.
If it is essential to create a new term, only do so after thoroughly verifying that the new term isn’t already being used to mean something else. Also verify if your new term is comparable to existing terms with a similar meaning.
Define technical terms in your documentation. Don’t assume that readers will understand them.
If you’re using a particular term, customarily use it across all your documentation, publication, websites, and concepts with consistency.
Cater your vocabulary for specific audiences and readers. For example, technical terminology would apt for a developer demographic, but not for a non-technical, beginner, or business-minded audience.
Research new terminology to stay up-to-date with the latest technological terms and industry approaches. Refer the latest technical and industry publications for demonstrated uses of new terms.
Be thoughtful of word choice – particularly avoid jargon, slang and ableist language. In a spoken and informal context, slang or jargon would suffice. But for achieving inclusive and accessible documentation for a global audience, slang and jargon hinders understanding more than simplifying it. Instead of using slang or jargon, use common and easy-to-understand terms.
Avoid using jargon if there is a better, comprehensible word for that specific term. Additionally, don’t use jargon if the term is familiar to only a small portion of your reader demographic. Only use jargon if it is absolutely needed to explain technical or software-related concepts.
If you’re doubtful of whether a particular term is jargon or a technical term, refer the Word list and usage dictionary; if it isn’t covered there, refer technical and industry publications for demonstration of common use. A particular term likely is jargon if you, your colleague, or reviewer thinks that it might be jargon. If the term is an abbreviation and you’re sure that your reader demographic is expected to understand the term, then you don’t need to spell it out. Otherwise, spell out abbreviations.
Common words are known for their standard definitions that are regularly used, and are familiar with most people. Use existing words in the most widely used meaning.
Don’t create new ways to describe an existing word.
Warning:Not recommended: Don’t use data unearthing or data excavating as an alternative for data mining.
Warning:Not recommended: The Gutenberger blocks are feature-packed.
Tip:Recommended: The blocks in GutenbergGutenbergThe Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ are feature-packed.
Similarly, don’t employ a totally different meaning to an existing, common word. For example, don’t use dictation to mean command.
If you have to use a word in a definition that is different from its widely used meaning, explain it with context.