: 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

@Ann1701686

Vote Up Vote Down

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)

Login to post a comment!