While completing the tech edit on the 2nd edition of the PHP Anthology the issue of linking came up; specifically, linking to authoritative reference material on the web. It came up because I would often link to a Wikipedia page and half of the editing team were opposed to such preferential treatment of one web site.
The issue isn’t simple one. Regarding PHP, the php.net manual is the authoritative reference site. The various web technology standards are also represented by authority web sites. For example XML-RPC has xmlrpc.com and CSS and XHTML have the W3C. But what about general topics like REST, design patterns or role-based access control? If you need reference material on such topics who can you trust?
I like Wikipedia because their pages are often an excellent focal point for a topic, are readable, contain links to other references and nerdy topics are always well represented and maintained. And of course, when using Google to search for general topics, Wikipedia often appears in the top 5 returned search results. So my options are often either link to Wikipedia and be fairly confident that it’s a good reference or spend an hour or so testing the remaining links, reading the articles, making judgments about suitability and finally choosing one site to link to.
There are several valid reasons not to link to Wikipedia that arose from the editing team’s discussions: it’s too easy to graffiti, a reader following the link in 6 months time may get completely different content to what you originally linked to, sometimes the quality of the writing is not great, there have been documented cases of inaccuracy or politically motivated editing of topics, and readers should be exposed to as much variety as possible.
So what makes a trustworthy reference web site? Here’s my wish list of attributes for the perfect reference material web site:
Readability:
- excellent written expression and clarity without being too dry, obtuse or academic
- text is well laid out and broken up into manageable sections
Accuracy & Trustworthiness:
- material is actively maintained
- known ambiguity is indicated
- no commercial bias
- site recognition from professionals
- site includes contributions by known experts
Longevity:
- site is well maintained
- site is reliable
- page URIs are meaningful (thus likely to not break over time, I have no confidence in URIs like
index.cfm?id=1234&lange=en&nav=5678&pg=4but I do in URIs likephp.net/strings)
So which reference sites do you trust and why?
Andrew TetlawiOS Developer, sometimes web developer and Technical Editor.
