BP Structure Examples

Summary points

(drawn from examples 1-10)

Having looked through the cited examples, they're all good. But one in particular is worth taking a look at: OpenFEC API (Beta) Documentation ... it's unintimidating to start with but allows folks to drill down to progressive levels of detail ... lot's of Javascript though (& I'm not an expert- so will need some help if we're to emulate this)

Also, @Linda has found an excellent resource (better living through documentation) that lists the top 20 tips for better tech communication. I'll list some of them here because they're right on cue:

1. AVOID GIANT BLOCKS OF TEXT!

2. SHOW AND HIDE CONTENT DYNAMICALLY

3. AVOID THE WORD 'JUST'

6. PROVIDE CODE EXAMPLES

7. MAKE SURE CODE EXAMPLES ARE OKAY TO COPY/PASTE

8. DON’T PUT IMPORTANT CONTENT DIRECTLY BEFORE OR AFTER A CODE SNIPPET

9. TELL PEOPLE WHAT KIND OF CODE EXAMPLE THEY ARE GETTING

13. INCLUDE GIT RESOURCES WHERE APPLICABLE

15. REMEMBER TO STATE WHAT PROBLEM YOU'RE SOLVING

16. PUT THE MOST IMPORTANT CONTENT NEAR THE BEGINNING

17. TURN LINKS INTO BUTTONS WHEN THEY ARE IMPORTANT

20. ACTIVELY SEEK FEEDBACK FROM OTHERS

These resonate with many of the pointers that are cited in the examples below ...

Here's my summary of the key points:

• best best practices are 'developer centric'- written for the people writing the code
  • in our case, the code definitely includes the content (in which case we're speaking to content publishers)
    • ¿ are we also seeking to provide example code-snippets to people writing or using APIs to work with that content? (I guess this depends on the best practices that emerge)
  • we need to make sure that we cover the broad spectrum of content publishers- as Ed said previously: "from someone crafting a web page to describe their village fête to Starbucks publishing the location of all their outlets via their GIS" (or words to similar effect)
• information provided must be actionable ... meaning that once you've read the details, you can do something that you couldn't do before; it's not just a description of what we're trying to achieve but how to achieve
• ease readers in with an overview at the beginning
  • each of our 7 themes should have an overview section
    • the overview should clarify what we're trying to achieve and summarise the procedure; to list the steps involved, with a brief description for each step and a link to a more detailed description (see Best Practices for Publishing Linked Data)
    • the overview should indicate why we're doing what we're doing ... e.g. what's the intended outcome, what are the benefits from the proposed approach
    • ¿ do we need something like Google Maps' "Quick Start steps" or Amazon's AWS SDK Getting Started guide that list any prerequisites or startup steps that need to be done?
  • the entire BP doc should have an overview- amongst other things, it should indicate why the BPs in presented are better than the current de facto approaches (e.g. better than Trad-GIS)
    • at meeting of 16-Sep-2015 we had consensus that we were approaching this from a "linked data perspective" (which doesn't necessarily mean RDF) ... we discussed that the most significant change in approach was the use of global identifiers (@Jeremy called them "web-scale foreign keys") that allow information from disparate sources to be reconciled ... @phila wants to avoid "using the web as a USB stick"
    • Jon Blower likely has some content for this section derived from the MELODIES project outputs
    • the overview might also indicate some common starting points for readers to get stuck in; e.g. "if you want to do this, start here; if you want to do that, start there"
    • declare the skills prerequisites for its readers, along with software/hardware requirements to implement the examples
• examples, examples, examples ... people learn by rote. Examples of content, examples of code, examples of application (etc.)
  • examples that can be tried out live and can be copied and reused
  • use foldable code snippets & examples (e.g. show/hide)
  • make sure code examples are okay to copy/paste
    • ¿ how to do this; where can we host working examples (e.g. of service end-points to interact with)?
    • json-ld.org (and many other sites) provide a sandbox where code can be tested; can we do this
    • @Linda notes that openlayers uses JSFiddle ... e.g. openlayers' clustering example
    • we can probably host developer resource in GitHub
    • note that the need to have cut&pastable examples makes use of the example.org domain difficult as it does not resolve ... we want our examples to work
• don't be afraid to cite bad practice as things to avoid
• simple to follow (even if the topic is complex)
  • this will be a big editorial challenge- making sure we use straightforward language; text that is concise and to the point
  • basics first - then the details
  • screen shots and diagrams are be useful to break up dense text
  • try to keep each section as a bite-size chunk of information ... with links to more detailed stuff as and when necessary ... most of the cited examples keep sections to no more than a dozen lines of text within a given section; each section has its own header and URL
  • Better Living Through Documentation says "Break up text to keep paragraphs short (under 4 sentences). Re-work sentences to use fewer words. Turn text into bullet points or numbered lists where possible."
  • best practices should be modular with each delivering a self-contained outcome which has value; don't require readers to eat the whole BP doc
    • ¿ can we build a pathway through the BP doc that allows readers to build their knowledge as they progress? ... or to dip in where they need to extend their existing knowledge?
• reference out to other resources (tutorials, primers, RECs, developer resources, repositories etc.)
  • don't repeat what others have covered if possible- signpost the authoritative source so the readers can find out more
  • direct links to developer resources (such as GitHub repositories)
    • ¿ how can we make sure that those [developer] resources that we link to remain available?
  • cross-reference to other best practices where necessary
    • ... which means that each best practice and sub-section must be identified with a URL- so that we (and others) can cite them
• include a glossary of terms- which probably reference other authoritative definitions
• include 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

Examples of Best Practice elsewhere

Please use this page to add links to examples of Best Practice you had found useful. These need not be related to Spatial, but should be examples we can learn from in terms of the structure, design and style. Remember the intended audience for our BP document are non spatial specialist who have spatial data to publish and/or which to develop applications to consumer spatial data.

1. Eddystone Project (Ed)

https://developers.google.com/beacons/overview?hl=en

A overview of Bluetooth LE technology for proximity based applications, I like the use of direct links to Github repositories of more detailed developer resources, while providing an overview of the technology. It could perhaps be improved by provided some examples of potential uses of the technology.

2. Publishing Linked Data (Alejandro)

http://www.w3.org/TR/ld-bp/

This document addresses the specific task of publishing a (-n open government) dataset as Linked Data on the Web. I found useful the Summary of Best Practices section, which lists the recommended steps with a brief description and the link to a more detailed explanation.

3. Linked Data: Evolving the Web into a Global Data Space (Frans)

http://linkeddatabook.com/

This book helped me a lot in making sense of the Linked Data concept. Things I like are:

1. It is comprehensive.
2. It discusses the concept at multiple levels (the 'how' as well as the 'why').
3. It is structured well, a chapter builds onto the previous chapter(s).
4. It does not shy away from saying that some things are not a good practice (e.g. blank nodes).
5. It keeps things as simple as possible.
6. It contains examples (that can be copied and reused).

4. w3schools.com (Frans)

http://www.w3schools.com/

A learning site for web developers, a good recource to quickly view the basics of a web technology. I like it because:

1. Its contents are very ecomonic - it shows a lot can be explained with a few words.
2. It keeps things as simple as possible.
3. It contains examples (that can be tried out live and can be copied and reused).
4. It has a consistent style for explaining things.
5. It is stuctured well (e.g. first the basics, then the details).
6. Next to the 'how' it explains the 'why'.
7. It is kept up to date (!).

5. developer-centric best practices: Google maps, Twitter and Amazon AWS (Jeremy)

Google maps

Twitter

Amazon AWS

1. good documentation
2. tutorials
3. example code

... the key point is that all these docs are provided by 'big players' with thousands of users, so they invest effort and time in getting the job done. Crucially: you get what you pay for.

6. Better Living Through Documentation (Linda)

http://datamade.us/blog/better-living-through-documentation/

A thorough list of recommendations on how to write developer-friendly documentation (and best practices). Contains many useful tips e.g. "don't put important content directly before or after a code snippet", "avoid the word 'just'" and "make sure code examples are okay to copy/paste".

7. OpenLayers 3 examples (Linda)

http://openlayers.org/en/v3.8.2/examples/cluster.html

Executes the "easy copy/paste of code" mantra extremely well. Code is copied to clipboard or JSFiddle with a single click. The latter is extremely useful for doing quick, one-off experiments.

8. The Federal Election Commission API (Linda)

https://api.open.fec.gov/developers

Crème de la crème of API documentation. Contains executable code, response examples, foldable code blocks, concise and to the pont text, enthusiastic calls for participation, etc.

9. mapschool (Linda)

http://mapschool.io/

mapschool explains geo in an extremely basic, and therefore accessible, way. This is the level of complexity/simplicity that the Best Practice docs should strive for to achieve adoption by non-geo developers.

10. civic hacking and digital government initiatives (Linda)

http://www.codeforamerica.org/

https://www.whitehouse.gov/digital/united-states-digital-service

https://18f.gsa.gov/ https://gds.blog.gov.uk/

Are all great examples of large (non-commercial) organizations that engage with developers by building great tools and writing superb documentation, but also by opening their process to external contributions (see e.g. this and this) and being positively outspoken about it.

Noteworthy examples of documentation are U.S. Digital Service Playbook by USDS and U.S. Federal Web Design Standards by 18F. Both are open to contributions through GitHub.

11. HyperCat - hypermedia catalogue (Payam)

http://www.hypercat.io/standard.html

HyperCat is designed to publish metadata about IoT data/resources over the web. It uses lightweight JSON-based hypermedia catalogue format for exposing collections of URIs.

1. Hypercat can be represented in JSON, RDF or other forms.
2. Linking hypermedia data catalogues
3. Defines a URI structure and a publishing format
4. Validation and publication tools and libraries are also available.

12. MapServer documentation and tutorial (Rachel)

http://www.mapserver.org/documentation.html http://www.mapserver.org/tutorial/index.html

In its own words: "MapServer is a popular Open Source project whose purpose is to display dynamic spatial maps over the Internet. " Good points, in common with those already summarised from examples 1-10:

1. starts from very simple overview, each simple concept or step is linked to sections with more advanced features
2. working demo data and code
3. written in very accessible language; glossary of all jargon
4. bite-size sections
5. users encouraged to help improve the documentation (via issue tracker)

Also:

1. introduction declares skills prerequisites for its readers along with software/hardware requirements; expected timeframe to complete the tutorial
2. FAQ that are expressed in the way a _real_ user would ask rather than questions in the language of the specialists