Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

50%
+0 −0
Q&A How to include external references when writing internal documentation?

The guiding principle in my experience is: put the link where the reader needs the referenced information. Examples: "This interface is like Somebody Else's Thing (link, or make SET a link itsel...

posted 5y ago by Monica Cellio‭  ·  last activity 5y ago by System‭

Answer
#3: Attribution notice added by user avatar System‭ · 2019-12-08T11:21:46Z (almost 5 years ago)
Source: https://writers.stackexchange.com/a/43592
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by (deleted user) · 2019-12-08T11:21:46Z (almost 5 years ago)
The guiding principle in my experience is: put the link where the reader needs the referenced information. Examples:

- "This interface is like Somebody Else's Thing (link, or make SET a link itself), and in addition..." -- put the link right there, because somebody unfamiliar with SET will need to at least skim the linked text to understand what you're about to say.

- "Stuff, stuff, and more stuff... Related background information: (links)" -- here your linked information is optional background stuff; a reader could skip it entirely and not be worse off. The "links" section you've described works fine for that.

Most cases will be somewhere in between -- the linked information is _helpful_ but not _required_. For these cases, you need to make a judgement call. If there are few links and you can add them "inline" (like in the first example) without making your document cumbersome, put them there because that's easier to both read and maintain. If there are lots of links and they're mostly tangential, collect them at the end -- and try to review the list from time to time to see if they're all still relevant.

#1: Imported from external source by user avatar System‭ · 2019-03-15T18:42:55Z (over 5 years ago)
Original score: 4