Go Back
1 Vote

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

1 Comment | Posted by Ace Olszowka to Documentation on 8/22/2019 8:59 PM
This is something we will be improving over time. The vast majority of our content began as printed documentation. As such, it had cross references, which were converted to links when we imported the content into our new web-based format. Printed documentation doesn’t lend itself to the number and variety of references typically available in topic-based documentation, so we agree this can be improved. This is one of a number of tasks we'll continue to work on as we optimize our content for the web.
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  
Please log in to comment on this idea.