Added 'About this Document' section with clarification between the terms 'best practice' and 'guideline'.
--- a/ldp-bp/ldp-bp.html Mon Jul 01 16:10:49 2013 -0500
+++ b/ldp-bp/ldp-bp.html Mon Jul 01 19:51:10 2013 -0500
@@ -89,19 +89,63 @@
</script>
</head>
<body>
- <section id='abstract'>This document provides best practice
- guidelines for Implementing Linked Data Platform servers, clients and
+
+ <section id='abstract'>This document provides best practices and general guidelines for Implementing Linked Data Platform servers, clients and
related systems.</section>
<section>
- <h2>Your Title</h2>
- <p>Your text...</p>
+
+ <h2>About this Document</h2>
+
+ <section>
+
+ <h3>Impetus</h3>
+
+ <p>While writing the Linked Data Platform Specification, the authors and contributors felt compelled to share common conventions and valuable lessons-learned. Yet, at the same time, they did not wish to impose or imply unnecessary restrictions, or to make the formal specification unnecessarily verbose. This document, along with the <a href="http://www.w3.org/2012/ldp/wiki/Primer">LDP Primer</a>, was therefore developed to provide additional context. Drawing upon the professional experiences of its authors and contributors, research into the rich history of all related technologies, and continuous feedback from the community at large, it aims to help system implementers:</p>
+ <ul>
+ <li>avoid common pitfalls,</li>
+ <li>improve quality, </li>
+ <li>improve development and maintenance efficiency, and</li>
+ <li>achieve greater interoperability with LDP’s within the enterprise, between enterprises, and across the World Wide Web.</li>
+ </ul>
+ </section>
+
+ <section>
+
+ <h3>Terminology</h3>
+
+ <p>For the purposes of this document, we have found it useful to make a minor, yet important distinction between the term 'best practice' and the term 'guideline'. For the purposes of this document, we define and differentiate the terms as such:</p>
+
+ <dl>
+ <dt>best practice</dt>
+ <dd>
+ A good implementation practice (method or technique) that has consistently shown results superior to those achieved with other means and that is used as a benchmark. Best practices within this document apply specifically to the ways that one should implement technology (i.e. LDP servers, clients, and related systems). In this document, the best practices might be used as a kind of check-list against which one can directly evaluate a system's design and code. Lack
+ of adherance to any given best practice, however, does not necessarily imply a lack of quality; they are recommendations that are said to be 'best' in most
+ cases and in most contexts, but not all. A best practice is always subject to improvement as we learn and evolve the Web together.
+ </dd>
+ <dt>guideline</dt>
+ <dd>A tip, a trick, a note, a suggestion, or answer to a frequently asked question. Guidelines within this document provide useful information that can
+ advance your knowledge and understanding and help you achieve a result, but that may not be directly applicable to your implementation or recognized
+ by consensus as the 'best' method or technique.</dd>
+ </dl>
+
+ <p>Please see the <a href="http://www.w3.org/TR/ld-glossary/">Linked Data Glossary</a> for definitions to a variety of terms related to the Linked Data sphere of knowledge.</p>
+
+ </section>
+
+ <section>
+ <h3>Prerequisites and Assumptions</h3>
+ <p class="note">
+ TO DO: Consider inserting some prereqs and assumptions here that help to clarify the audience, level of understanding expected from that audience. Perhaps, provide an example learning path for the uninitiated.</p>
+ </section>
+
</section>
<section>
- <h2>Best Practice Category A</h2>
+ <h2>Best Practices</h2>
<section>
+
<h3>Use relative URIs</h3>
<p class="note">
@@ -444,13 +488,13 @@
</section>
<section>
- <h2>Best Practice Category B</h2>
+ <h2>Guidelines</h2>
<section>
- <h3>Practice 1</h3>
+ <h3>Guideline 1</h3>
<p>Eplurbis unum...</p>
</section>
<section>
- <h3>Practice 2</h3>
+ <h3>Guideline 2</h3>
<p>Eplurbis unum...</p>
</section>
</section>