RE: What makes a 'best' best practice?

Hi Jeremy,

For what it’s worth, I’ve added another example (MapServer) to the wiki of best practice examples. Most of the points overlap with those you’ve already summarised.
In addition, this example has

-an introduction that declares the skills prerequisites for its readers, along with software/hardware requirements to implement the examples

-FAQ that are expressed in the way a _real_ user would ask rather than questions in the language of the specialists. A developer should be able to google their question or problem and find the relevant section in our best practices.

Other general points that I think would be good:

-The document should be very clear on the version numbers of any libraries/standards etc for which the best practice and any examples are known to be valid. (One of the biggest headaches as a developer is managing compatibility between a range of software components that you need to work together but each are continuously evolving; the compatibility issue can fall in the gaps between documentations). This is related to the issue of durability.

-To support the “why we’re doing what we’re doing”, the overview section could describe some common problems, pitfalls and misuse of spatial data that we are trying to address.

-Personally, I like having the option of printing an entire document too, in addition to the show/hide/sectioned online version.

Cheers,
Rachel


From: Jeremy Tandy [mailto:jeremy.tandy@gmail.com]
Sent: 23 September 2015 11:35
To: SDW WG Public List
Subject: What makes a 'best' best practice?

Hi-

Many thanks for the references to your favourite (technical) documentation examples [1].

I've summarised the key points [2] - there are some pretty clear things that we need to do ... and some questions too (for example- about publishing working examples and other resources that are as durable as the W3C needs).

Happy to discuss on the call today or via email. Please advise if
a) I have missed anything that you regard as a "must have"
b) there's anything that you see as a "don't do that"

Regards, Jeremy

[1]: https://www.w3.org/2015/spatial/wiki/BP_Structure_Examples

[2]: https://www.w3.org/2015/spatial/wiki/BP_Structure_Examples#Summary_points

________________________________
This message (and any attachments) is for the recipient only. NERC is subject to the Freedom of Information Act 2000 and the contents of this email and any reply you make may be disclosed by NERC unless it is exempt from release under the Act. Any material supplied to NERC may be stored in an electronic records management system.
________________________________