User Tools

Site Tools



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

Link to this comparison view

Next revision
Previous revision
content:dev:techdoc [17/12/2012 21:20]
Andrew Bettison created
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: 
-  * API documentation and specifications +  * protocol and API specifications 
-  * build, test and installation instructions +  * instructions for developers: build, configuration, test and installation 
-  * release notes +  * documents accompanying specific versions: release notes, credits, privacy and data retention policies, licenses
-  * privacy and data retention policies +
-  * architectural notes +
-  * contributor lists+
-All Serval Mesh technical documentation resides within its respective [[content:process:git|Git]] source code repositories, for the following reasons: +==== Where to find technical documents ====
-  * 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.+
-The [[:main_page|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:+All technical documentation resides in [[git|Git]] source code repositories: 
 +[[:content:servalmesh:]] -- the [[|Batphone Git repository]] contains: 
 +  * [[|]] 
 +  * [[|]] -- build instructions 
 +  * [[|]] -- latest release notes 
 +  * [[|]] -- privacy and data retention policy 
 +  * [[|]] -- contributors and acknowledgements 
 +  * [[|doc/]] -- technical document index 
 +[[:content:servaldna:]] -- the [[|Serval DNA Git repository]] contains: 
 +  * [[|]] 
 +  * [[|]] -- build instructions 
 +  * [[|]] -- list of contributors 
 +  * [[|doc/]] -- technical document index 
 +[[: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+
   * 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.1355808005.txt.gz · Last modified: 17/12/2012 21:20 by Andrew Bettison