Re: What makes a 'best' best practice?

Hi Rachel- thanks for the input. I've added your top-level points to the
summary [1].

I agree with the need to create a printable version; any clever javascript
needs to have a complementary "flat" view. For example, if you look at the
doc I've been producing for CSV on the Web [2], you'll see a "show/hide
detailed annotations". The print version should have these shown by default.

Jeremy

[1]:
https://www.w3.org/2015/spatial/wiki/BP_Structure_Examples#Summary_points
[2]:
http://w3c.github.io/csvw/publishing-snapshots/CR-csv2rdf/Overview.html#examples

On Fri, 25 Sep 2015 at 12:21 Heaven, Rachel E. <reh@bgs.ac.uk> wrote:

> 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.
> ------------------------------
>