Table of Contents
Technical Documentation
Technical documentation includes:
- protocol and API specifications
- instructions for developers: build, configuration, test and installation
- documents accompanying specific versions: release notes, credits, privacy and data retention policies, licenses
Where to find technical documents
All technical documentation resides in Git source code repositories:
Serval Mesh – the Batphone Git repository contains:
- INSTALL.md – build instructions
- CURRENT-RELEASE.md – latest release notes
- PRIVACY.md – privacy and data retention policy
- CREDITS.md – contributors and acknowledgements
- doc/ – technical document index
Serval DNA – the Serval DNA Git repository contains:
- INSTALL.md – build instructions
- CONTRIBUTORS.md – list of contributors
- doc/ – technical document index
Serval tools – the Serval Tools Git repository contains:
- doc/ – technical document index
Format
All 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.
- 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:
**Copyright 2014 Serval Project Inc.** **Portions Copyright 2014 Your Name**
- If creating a new document, ensure it contains the following back matter:
----- **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]: http://creativecommons.org/licenses/by/4.0/
For more information about the Creative Commons Attribution license:
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
- general Serval Project practices and policies
- 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
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.