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 [03/03/2013 22:31]
Andrew Bettison Add section headings, link to examples on GitHub, re-write bullet points a bit for clarity 		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:
-====== Serval Project Technical Documentation ======+====== Technical Documentation ======
  
-All 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 +
-  * names of contributors+
  
-==== What belongs in Git ====+==== Where to find technical documents ====
  
-All Serval Mesh technical documentation resides within its respective [[content:process: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 [[https://github.com/servalproject/batphone/|Batphone Git repository]] contains: 
-  * [[https://github.com/servalproject/batphone/blob/development/INSTALL.md|Batphone build and install instructions]] +  * [[https://github.com/servalproject/batphone/blob/development/README.md|README.md]] 
-  * [[https://github.com/servalproject/batphone/blob/development/doc/RELEASE-0.90.md|Serval Mesh 0.90 Release Notes]] +  * [[https://github.com/servalproject/batphone/blob/development/INSTALL.md|INSTALL.md]] -- build instructions 
-  * [[https://github.com/servalproject/serval-dna/blob/development/doc/Servald-Configuration.md|Serval DNA configuration 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
  
-==== What belongs in the Wiki ====+[[: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
  
-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:+[[: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 ==== 
 + 
 +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 "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> 
 +----- 
 +**Copyright 2014 Your Name**   
 +![CC-BY-4.0](./cc-by-4.0.png) 
 +This document is available under the [Creative Commons Attribution 4.0 International licence][CC BY 4.0]. 
 + 
 +... 
 + 
 +[CC BY 4.0]: http://creativecommons.org/licenses/by/4.0/ 
 +</code> 
 + 
 +For more information about the Creative Commons Attribution license: 
 +  * [[http://learn.creativecommons.org/wp-content/uploads/2009/07/ccLearn_primer-Why_CC_BY.pdf|Why CC-BY?]] 
 +  * [[http://creativecommons.org/weblog/entry/18906|The Shuttleworth Foundation on CC BY as default and commercial enterprises in education]] 
 +  * [[http://wiki.creativecommons.org/Marking/Users|best practices for attribution]] 
 +  * [[http://creativecommons.org.au/content/attributingccmaterials.pdf|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 [[https://help.github.com/articles/github-flavored-markdown|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.1362378711.txt.gz · Last modified: 03/03/2013 22:31 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