Often I find myself solving bugs by finding the answer on Stack Overflow. Is it bad practice to add a snippet of why I did what I did and then add a link to an article or page from the web?
This is why companies should have its own knowledge repository. For instance, my company have a corporative Redmine which is used for project's management, ticketing (bugs and tasks tracking) and the tool I use most, a wiki. All these features per project :-)
What do we have at project's wiki?
- Links to documentation: Functional, Technical, Architecture, requirements.
- Actors involved: Project Manager, Devs, Customer's Key Account managers, ...
- Description per environment: Virtual Machines, O.S, servers, configurations...
- Misc: Any important/interesting thing (related to the project) learnt during the project's lifetime.
- Some more pages.
I put bibliography (links) at Misc wiki. But only from those I trust:
- Stack Overflow: Positive votes and well argued
- Software Engineering Stackexchange: Positive votes and well argued
- MKyong.com: I like this page. It's really useful and its tutorials are really easy to follow
- W3Schools: Its documentation is interactive (most of the cases) and user-friendly.
- OWASP: For referencing issues related to security and vulnerabilities
- Official web pages: Sometimes the best tutorials or explanations are at official web pages.
My bibliography comes with a summary typed down by me, in order to ensure that I have understood what I'm linking to. I try to keep Javadoc as clear as possible. Every link in the code is referencing the Redmine's wiki or the Redmine's issue code.
In absence of tools like Redmine, I found to be useful Markdown files to be useful for these purposes. Overall for developers due to these files are in the SCM and comes along with the code.
Links to the web are somewhat problematic as documentation because the internet doesn't guarantee that the content you're seeing behind them will be the same that a future doc reader will see. If possible, strive to link only to resources that are very unlikely to change.
For instance, when you link to Wikipedia, you should link explicitly to today's version rather than the generic article name. For stackexchange.com, well, at the moment it looks unlikely to go away, but questions get edited or even deleted all the time, and in five year's time a hot new gathering point might have come along. I wouldn't risk hanging documentation that carries substantial business value on a site that is so external to your organization.