Document title

Author Karsten Schmidt (
Date 2016-08-02 09:24:13

Table of Contents

1 Introduction

1.1 TODO Abstract

This document is a demonstration of the template, primarily intended to simplify the creation & maintenance of technical specifications written in Org-mode.

All diagrams in this document are autogenerated from embedded code block snippets in the original .org file. See Appendix B for more information.

Brief outline description of the document1

1.2 DONE Scope

Topics covered by this specification:

1.3 Status of This Document

May Be Superseded

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

Changes since the last version

  • fix typo in section/
  • move major sections into separate files in /sections dir
  • update notice block handling
  • remove obsolete comment about changelog evaluation
  • add graphviz example & styles, add notice block example, add property export option, update intro
  • simplify plantuml evaluation (now automated)
  • bugfix changelog (only consider doc, no other project files)
  • bugfix git tag handling for changelog
  • add footnote example, use macro for publication date

1.4 Conventions

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in RFC2119.

Since a document and project of this nature deals with a large number of technologies, each with their own set of acronyms, please refer to the glossary in Appendix A, which briefly explains some of them.

1.4.1 Definition of project specific terms

In this document:

Term A
is a…
Term B
is a…

2 System architecture


Example of generating a GraphViz visualization:


2.1 System actors, roles & responsibilities

2.1.1 Users

2.1.2 Client

2.1.3 Server

2.2 General system design guidelines

2.2.1 User experience

2.2.2 Accessibility

2.2.3 Data formats

2.2.4 Performance

2.2.5 Security

2.2.6 Layered architecture

Example of generating block diagrams from ASCII art using ditaa:


Figure 2: Top-level, schematic overview of layered client architecture

2.3 Client data model

2.3.1 Overview

Example of generating UML diagrams from textual descriptions using plantuml:


Figure 3: Schematic overview of client side data entities

In the following sections each data field is expressed with type information, in Java style pseudo-code form.

2.3.2 User

Field Required Description
name N User name
email N User email
role Y One of possible values defined by UserRole

Example PlantUML diagram snippet defining the User class in above diagram. The full diagram itself is defined in the file /sections/, which is not exported to HTML.

class User {
  String name
  String email
  UserRole role
} User roles
Value Description
ANONYMOUS any non-logged in user
USER logged in, registered user with default permissions
ADMIN logged in, registered user with admin permissions
enum UserRole {

2.4 Technologies used

This section lists the currently envisaged set of technologies used to implement the system. Links & further explanations of the various projects are provided in Appendix A.

Modern dialect of Lisp, compiled to optimized JavaScript

3 Client / server communication

3.1 Server API requirements

3.1.1 Security considerations

3.1.2 HTTP requests

The following table summarizes standard HTTP REST requests (as per RFC7231):

HTTP Verb Client intention HTTP Status HTTP Status
    (successful) (error)
POST create a new resource 201 & redirect 400 / 403 / 404
PUT update an existing resource 200 / 204 400 / 403 / 404 / 409
GET read an existing resource 200 400 / 403 / 404
DELETE delete an existing resource 200 / 204 400 / 403 / 404 / 409

3.2 Server routes

3.2.1 POST /users/login

Param Required Description
email Y User's registered email address
pass Y User password

Requires authentication: NO

Description: Attempts to authenticate user based on given credentials.


{"status": "ok"}
{"status": "error"}

3.3 Clientside SPA routes

3.3.1 Route: /login

  • Displays login dialog
  • HTTP POST credentials to server /login route
  • Redirects to SPA main page

3.3.2 Route: /media/:media_id

Param Type Description
media_id UUID Media asset ID
  • Retrieves media asset from server
  • Displays media asset

4 Appendix A - Glossary   informative

Amazon Web Services, cloud service provider.
A modern dialect of Lisp compiling to optimized JavaScript using Google Closure compiler.
Create, Read, Update, Delete - usually refers to adminstration tasks in CMS / database applications
Extensible Data Notation, lightweight, data exchange format similar to JSON, but with extensible type support. Native serialization format for Clojure / ClojureScript.
Google Closure compiler
Currently best optimizing JavaScript to JavaScript compiler. Performs static analysis and whole program optimizations to allow efficient deployment of large-scale applications. Supports dynamic module loading.
Google Closure library
Google's standard library for cross-browser JavaScript application development. All encompassing & optimized for Closure compiler.
JavaScript Object Notation, lightweight defacto industry standard data exchange format, especially if parts of a system involve JavaScript.
Single-page Application. Refers to a client-side JavaScript web application model, usually with different UI modules. All essential assets (HTML, JS, CSS) are loaded only once and lead to more fluid user experience. Examples: GMail, Google Docs etc.
Industry defacto standard documentation system for REST API endpoints.
Universally unique identifier, standardized a 128bit value, usually expressed as 32 hex characters.

5 Appendix B - Building this document   informative

This document (including all diagrams) has been generated using the following tools:

5.1 Re-publish an HTML version

The entire source code for this document is stored in the file Please follow these steps to publish an updated HTML version of the specification:

  1. Install the above listed tools. On OSX Ditaa, GraphViz and PlantUML can be installed via Homebrew:
brew update && brew install ditaa graphviz plantuml
  1. In Emacs type M-x load-file RET /path/to/org-theme/config.el
  2. Open the file in Emacs
  3. Press C-c C-e h o to launch the export selection dialog, export as HTML and automatically open the file in your web browser

Note: The export process will re-generate the changelog (only in the exported HTML), re-create any diagrams and replace any existing rendered diagram files.

5.2 Re-publish PDF

Follow the same instructions as for HTML and then print the document to a PDF file via your browser's print dialog. Print style sheets are included in the file css/styles.css.



Example footnote, can also contain links.