: Re: How to include external references when writing internal documentation? In the IT industry, we often write a lot of technical documentation meant for internal use only. Those documents are often

@Goswami879

Vote Up Vote Down

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.

(0)

Login to post a comment!