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 [20/05/2014 19:24]
Andrew Bettison [Format] "basic Markdown" -> "standard Markdown" 		content:dev:techdoc [21/05/2014 01:05] (current)
Andrew Bettison [Where to find technical documents] remove link to Batphone LICENSE.md
Line 2: Line 2:
  
 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 (`CREDITS.md`)+ 
 +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 ==== ==== Format ====
Line 16: Line 35:
   * 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]]   * 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   * 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 43: 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.1400639049.txt.gz · Last modified: 20/05/2014 19:24 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