The Serval Project Wiki

User Tools

Site Tools

You are here: The Serval Project Wiki » content » Development » Technical Documentation
Trace:
content:dev:techdoc

Differences

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 [19/05/2014 17:57]
Andrew Bettison [What belongs in Git] update re licencing and GFM 		content:dev:techdoc [21/05/2014 01:05] (current)
Andrew Bettison [Where to find technical documents] remove link to Batphone LICENSE.md
Line 1: Line 1:
 ====== Technical Documentation ====== ====== Technical Documentation ======
- 
-All [[:content:about|Serval Project]] technical documentation is (or should be) in [[http://daringfireball.net/projects/markdown/|Markdown]] format, which is [[http://en.wikipedia.org/wiki/Plain_text|plain text]] in [[http://en.wikipedia.org/wiki/UTF-8|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 +==== Where to find technical documents ==== 
-  * names of contributors+ 
 +All technical documentation resides in [[git|Git]] source code repositories: 
 + 
 +[[:content:servalmesh:]] -- the [[https://github.com/servalproject/batphone/|Batphone Git repository]] contains: 
 +  * [[https://github.com/servalproject/batphone/blob/development/README.md|README.md]] 
 +  * [[https://github.com/servalproject/batphone/blob/development/INSTALL.md|INSTALL.md]] -- build instructions 
 +  * [[https://github.com/servalproject/batphone/blob/development/CURRENT-RELEASE.md|CURRENT-RELEASE.md]] -- latest release notes 
 +  * [[https://github.com/servalproject/batphone/blob/development/PRIVACY.md|PRIVACY.md]] -- privacy and data retention policy 
 +  * [[https://github.com/servalproject/batphone/blob/development/CREDITS.md|CREDITS.md]] -- contributors and acknowledgements 
 +  * [[https://github.com/servalproject/batphone/blob/development/doc/|doc/]] -- technical document index 
 + 
 +[[:content:servaldna:]] -- the [[https://github.com/servalproject/serval-dna/|Serval DNA Git repository]] contains: 
 +  * [[https://github.com/servalproject/serval-dna/blob/development/README.md|README.md]] 
 +  * [[https://github.com/servalproject/serval-dna/blob/development/INSTALL.md|INSTALL.md]] -- build instructions 
 +  * [[https://github.com/servalproject/serval-dna/blob/development/CONTRIBUTORS.md|CONTRIBUTORS.md]] -- list of contributors 
 +  * [[https://github.com/servalproject/serval-dna/blob/development/doc/|doc/]] -- technical document index 
 + 
 +[[:content:dev:servaltools:]] -- the [[https://github.com/servalproject/serval-tools/|Serval Tools Git repository]] contains: 
 +  * [[https://github.com/servalproject/serval-tools/blob/development/README.md|README.md]] 
 +  * [[https://github.com/servalproject/serval-tools/blob/development/doc/|doc/]] -- technical document index 
 + 
 +==== Format ==== 
 + 
 +All [[:content:about|Serval Project]] technical documentation is (or should be) in [[https://help.github.com/articles/github-flavored-markdown|GitHub Flavoured Markdown (GFM)]]. 
 +  * [[https://help.github.com/articles/github-flavored-markdown|GFM]] is an extension of [[http://daringfireball.net/projects/markdown/|standard Markdown]] 
 +  * Markdown is [[http://en.wikipedia.org/wiki/Plain_text|plain text]] in [[http://en.wikipedia.org/wiki/UTF-8|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 [[http://en.wikipedia.org/wiki/HTML|HTML]] or [[http://en.wikipedia.org/wiki/Pdf|PDF]] 
 +  * Both standard and GitHub Flavoured Markdown are supported by the [[http://johnmacfarlane.net/pandoc/|Pandoc]] markdown conversion tool
  
 ==== Copyright and licensing ==== ==== Copyright and licensing ====
Line 15: Line 40:
 All technical documentation is licensed to the public under the [[http://creativecommons.org/licenses/by-sa/4.0/|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. All technical documentation is licensed to the public under the [[http://creativecommons.org/licenses/by-sa/4.0/|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 copyright notice to the existing list in the document+  * 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**   
 +</code>
   * If creating a new document, ensure it contains the following back matter:<code>   * If creating a new document, ensure it contains the following back matter:<code>
 ----- -----
-**Copyright 2014 Your Name.**  +**Copyright 2014 Your Name**  
 ![CC-BY-4.0](./cc-by-4.0.png) ![CC-BY-4.0](./cc-by-4.0.png)
-Available under the [Creative Commons Attribution 4.0 International licence][CC BY 4.0].+This document is available under the [Creative Commons Attribution 4.0 International licence][CC BY 4.0].
  
 ... ...
Line 33: Line 61:
   * [[http://creativecommons.org.au/content/attributingccmaterials.pdf|Attributing CC materials]]   * [[http://creativecommons.org.au/content/attributingccmaterials.pdf|Attributing CC materials]]
  
-==== What belongs in Git ====+==== Why is technical documentation kept in Git repositories? ====
  
-All [[:content:servalmesh:|Serval Mesh]] and [[:content:servaldna:|Serval DNA]] technical documentation resides within its respective [[git|Git]] source code repository, for the following reasons: +  * It is **closely tied to specific versions** of software components, 
-  * it is **closely tied to specific versions** of software components, +  * It **must be updated** as new software versions are produced, 
-  * it **must be updated** as new software versions are produced, +  * **Prior versions** must be available, just like source code, 
-  * **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 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, 
-  * 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, 
-  * authorship can be traced in detail using the Git commit history, +  * GitHub [[https://help.github.com/articles/github-flavored-markdown|renders Markdown nicely]] so it provides URLs and on-line access to all technical documents.
-  * GitHub [[https://help.github.com/articles/github-flavored-markdown|renders Markdown nicely]] so it provides URLs and on-line access to all technical documents. +
  
-Some good examples of technical documentation are: +==== What belongs in the Developer Wiki? ====
-  * [[https://github.com/servalproject/batphone/blob/development/INSTALL.md|Batphone build and install instructions]] +
-  * [[https://github.com/servalproject/batphone/blob/development/doc/RELEASE-0.90.md|Serval Mesh 0.90 Release Notes]] +
-  * [[https://github.com/servalproject/serval-dna/blob/development/doc/Servald-Configuration.md|Serval DNA configuration instructions]]+
  
-==== What belongs in the Wiki ==== +The [[:|Serval Project Developer Wiki]] contains documents that are **not closely tied to specific software versions**, such as:
- +
-The [[wiki|Serval Project 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 practices 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.1400547452.txt.gz · Last modified: 19/05/2014 17:57 by Andrew Bettison

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution 4.0 International
CC Attribution 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki