User Tools

Site Tools



This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
content:dev:techdoc [02/05/2013 18:43] external edit
content:dev:techdoc [21/05/2014 01:05] (current)
Andrew Bettison [Where to find technical documents] remove link to Batphone
Line 1: Line 1:
-====== Serval Project Technical Documentation ======+====== Technical Documentation ======
-All Serval Project technical documentation is (or should be) in [[|Markdown]] format, which is [[|plain text]] in [[|UTF-8]] encoding using a regular notation for headers, emphasis, links, etc.  Technical documentation includes: +Technical documentation includes: 
-  * release notes +  * protocol and API specifications 
-  * build, test and installation instructions +  * instructions for developers: build, configuration, test and installation 
-  * privacy and data retention policies (which must be distributed with the software) +  * documents accompanying specific versions: release notes, credits, privacy and data retention policies, licenses
-  * architectural notes relating specifically to the software +
-  * API documentation and specifications +
-  * names of contributors+
-==== What belongs in Git ====+==== Where to find technical documents ====
-All Serval Mesh technical documentation resides within its respective [[git|Git]] source code repositories, for the following reasons: +All technical documentation resides in [[git|Git]] source code repositories:
-  * it is closely tied to specific versions of software components, +
-  * it must be updated as new software versions are produced, +
-  * prior versions of technical documents must be available along with prior versions of the source code, +
-  * it is produced and reviewed by the same developers who work on the source code, +
-  * it is subject to the same copyright assignment, licensing and acceptance procedures as the source code, +
-  * GitHub renders Markdown and other structured text documents nicely.+
-Some good examples of technical documentation are+[[:content:servalmesh:]] -- the [[|Batphone Git repository]] contains
-  * [[|Batphone build and install instructions]] +  * [[|]] 
-  * [[|Serval Mesh 0.90 Release Notes]] +  * [[|]] -- build instructions 
-  * [[|Serval DNA configuration instructions]]+  * [[|]] -- latest release notes 
 +  * [[|]] -- privacy and data retention policy 
 +  * [[|]] -- contributors and acknowledgements 
 +  * [[|doc/]] -- technical document index
-==== What belongs in the Wiki ====+[[:content:servaldna:]] -- the [[|Serval DNA Git repository]] contains: 
 +  * [[|]] 
 +  * [[|]] -- build instructions 
 +  * [[|]] -- list of contributors 
 +  * [[|doc/]] -- technical document index
-The [[wiki|Serval Project Wiki]] is used to host documents that are largely independent of specific software versions and releases, and **not** closely tied to software development processes, such as:+[[:content:dev:servaltools:]] -- the [[|Serval Tools Git repository]] contains: 
 +  * [[|]] 
 +  * [[|doc/]] -- technical document index 
 +==== Format ==== 
 +All [[:content:about|Serval Project]] technical documentation is (or should be) in [[|GitHub Flavoured Markdown (GFM)]]. 
 +  * [[|GFM]] is an extension of [[|standard Markdown]] 
 +  * Markdown is [[|plain text]] in [[|UTF-8]] encoding with readable notation for headers, emphasis, links, etc. 
 +  * Markdown has the benefit that it can be read as plain text, but can be made richer and more interactive by rendering it to [[|HTML]] or [[|PDF]] 
 +  * Both standard and GitHub Flavoured Markdown are supported by the [[|Pandoc]] markdown conversion tool 
 +==== Copyright and licensing ==== 
 +All technical documentation is licensed to the public under the [[|CC BY 4.0]] license.  Contributors should either [[..:|assign their copyright to Serval Project Inc.]] or ensure their name is in the list of copyright holders in the back matter. 
 +  * If modifying an existing document, simply append a new "portions copyright" notice to the existing list in the document:<code> 
 +**Copyright 2014 Serval Project Inc.**   
 +**Portions Copyright 2014 Your Name**   
 +  * If creating a new document, ensure it contains the following back matter:<code> 
 +**Copyright 2014 Your Name**   
 +This document is available under the [Creative Commons Attribution 4.0 International licence][CC BY 4.0]. 
 +[CC BY 4.0]: 
 +For more information about the Creative Commons Attribution license: 
 +  * [[|Why CC-BY?]] 
 +  * [[|The Shuttleworth Foundation on CC BY as default and commercial enterprises in education]] 
 +  * [[|best practices for attribution]] 
 +  * [[|Attributing CC materials]] 
 +==== Why is technical documentation kept in Git repositories? ==== 
 +  * It is **closely tied to specific versions** of software components, 
 +  * It **must be updated** as new software versions are produced, 
 +  * **Prior versions** must be available, just like source code, 
 +  * It is produced and reviewed by the **same developers** who work on the source code, 
 +  * It is core Intellectual Property, and thus requires explicit **copyright assignment or licensing**, just like source code, 
 +  * Authorship can be traced in detail using the Git commit history, 
 +  * GitHub [[|renders Markdown nicely]] so it provides URLs and on-line access to all technical documents. 
 +==== What belongs in the Developer Wiki? ==== 
 +The [[:|Serval Project Developer Wiki]] contains documents that are **not closely tied to specific software versions**, such as:
   * orientation and introductory material   * orientation and introductory material
-  * general Serval Project procedures and policies +  * general Serval Project practices and policies
-  * general information for developers and contributors, including general architectural and API design+
   * road map and other long-term planning material   * road map and other long-term planning material
 +  * general information for developers and contributors, including general architectural and API design notes
   * lists of useful resources   * lists of useful resources
 +The Developer Wiki **MUST NOT** contain copies of technical documents whose definitive source is a Git repository, because such copies will not be maintained and will fall out of date, leading to confusion and poor community engagement.
content/dev/techdoc.1367545404.txt.gz · Last modified: 02/05/2013 20:22 (external edit)