Documentation Should Be Improved To Include Keywords / Concepts on Seperate Page and Then Linked
Several sections of the documentation assume a base knowledge of domain specific keywords and concepts. While seasoned developers and documentation writers can quickly infer their meaning based on their background it is difficult for new developers to pick up on this. To complicate matters it appears little of this is documented explicitly.
It would be best if the Documentation could follow the Wikipedia Manual of Style/Linking (https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Linking) specifically:
An article is said to be underlinked if words are not linked and are needed to aid understanding of the article. In general, links should be created for:
- Relevant connections to the subject of another article that will help readers understand the article more fully (see the example below). This can include people, events, and topics that already have an article or that clearly deserve one, so long as the link is relevant to the article in question.
- Articles with relevant information, for example: "see Fourier series for relevant background"
- Articles explaining words of technical terms, jargon or slang expressions/phrases—but you could also provide a concise definition instead of or in addition to a link. If there is no appropriate Wikipedia article, an interwikimedia link to Wiktionary could be used.
- Proper names that are likely to be unfamiliar to readers
Do not be afraid to create links to potential articles that do not yet exist
Thanks for the input. If you find a particular topic that could use more links, please let us know by using the “Comment on this page” link at the bottom of the page.
10/18/2019 2:52 PM 0