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 stored in an internal wiki and accessed when the need arises.
The content of the documents is not relevant here; the only relevant fact is that in the IT field you are not supposed to reinvent the wheel. When writing a piece of code, or documenting a procedure, you are in fact supposed to search on Google (or SE sites, nonetheless) for others having faced a similar situation.
So, when it comes down to actually documenting what you have done,
What is the best way to cite external references?
I often include a small list section with links at the end (or at the start) of the page, but I'm not sure it is the best method.
Keep in mind that internal documentation is not supposed to be read, ever, by customers. It usually stays private between colleagues.
3 answers
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 comment threads
I like Monica's answer -- my answer here is about how to be sure these links are still viable in the future.
If others are also making the documents, I encourage "casual citation", so there's not the stress of Proper Bibliographic Formatting, but as long as the URL is there, then readers can get to where the writer went.
To be sure that it's still there in the future, I often advised them also to go to the WayBack Machine on Archive.org, and there's an option there to manually copy archive that specific page.
For my classes, I'd often do the archive.org thing, then feed that longer link into TinyURL, so I'd have a shorter (though less identifiable) link to put on our resources, and it would show the version of the site/exercise that I planned for.
(This won't work at my workplace -- archive.org is blocked! but in most of the world, it should be fine. And it's not proof against robots.txt exclusions, which means the page won't be on archive.org.)
I do typically like to have a Visible Link, with the URL spelled out in case there's an error or change. If I copied an extra space into the link, someone can easily copy it. If the site did a redesign, with the original page title, it's a lot easier to search.
0 comment threads
This depends largely on the way existing documentation is written. Normally you have some kind of template that you can use for most documents. This template should illustrate how to cite external references. In case it does not show you how to do it you should have a look at other documents or for example ask colleagues who have been in the company for longer than you. That is because most companies develop an internal culture with internal norms and guidelines - what works for one company might not work for another company. The differences between small startups, big old-school companies and different industries are too big to allow a standard approach that fits for everyone.
If none of these lead you to an answer then it might be that this is simply not that important in your company for internal documentation. If people don't care about it you should re-think whether you want to spend time on this issue.
But in general I think that it's important and useful to have a guideline for external references. So if you can't find anything you might want to start something. You already mention that you have a small list section at the end or start. This might be good for smaller documentation because everything is in one place.
Another option would be to refer to your source whenever it occurs. Simply place an in-line link like you did for your Wikipedia link to the phrase "reinvent the wheel" or ad a footnote with such a link, again depending on the general style of presenting additional information and the specific medium you are using for communicating and documenting. Web-frontend based tools like Confluence work different from Word-documents for example. They often look quite different in my experience.
If you have a lot of documentation or just a really, really long document you might want to do something that's a bit more "formal" and make a short reference or link in-line and an additional entry at the end in a section dedicated to your sources.
If there is something that you always use as an external reference you could also make a document that is specifically dedicated to listing "standard external references" for everyone who regularly has to read different documents for example from the project you are working on.
I found that documentation for external tools is also a valuable source of finding guidelines for documentation. The people in your field and company are used to that type of documentation, so presenting them something similar makes it easier for others to find the important parts and to read your documentation without needing additional explanation. It's obviously intended to be read by customers, but that doesn't mean it's useless as a source of inspiration for internal documentation.
There are obviously also regional differences. Reading stuff from people from other countries can feel weird if you are not used to it because everyone has their own "style". There is no strict "How to document" guide that everyone agreed to use. Sadly... It would make a lot of communication so much easier if there was something like that...
Source for my experience: I am a software developer from Germany.
0 comment threads
0 comment threads