User Tools

Site Tools


This is an old revision of the document!

Technical Documentation

Technical documentation includes:

  • release notes
  • build, test and installation instructions
  • privacy and data retention policies (which must be distributed with the software)
  • architectural notes relating specifically to the software
  • API documentation and specifications
  • names of contributors (``)


All Serval Project technical documentation is (or should be) in GitHub Flavoured Markdown (GFM).

  • GFM is an extension of basic 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 basic Markdown and GFM are supported by the Pandoc markdown conversion tool

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 copyright notice to the existing list in the document
  • If creating a new document, ensure it contains the following back matter:
    **Copyright 2014 Your Name.**  
    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:

What belongs in Git

All Serval Mesh and Serval DNA technical documentation resides within its respective Git source code repository, for the following reasons:

  • 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.

Some good examples of technical documentation are:

What belongs in the Wiki

The Serval Project Wiki contains documents that are not closely tied to specific software versions, such as:

  • orientation and introductory material
  • 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
  • lists of useful resources
content/dev/techdoc.1400548113.txt.gz · Last modified: 19/05/2014 18:08 by Andrew Bettison