Software Project Documentation @ GitHub

---

Introduction

The following documents are used to provide consistent information regarding the 52°North software pages hosted at GitHub https://github.com/52North. Several core software projects are also displayed on the 52°North website. Please follow the guidelines to the README.md below. In addition, the information contained in the CONTRIBUTING.md should also be included in the GITHub Pages.

README.md

The README.md document should contain information pertinent to each software project from a marketing point of view. In addition, please include and send a screen shot, graphic, image, logo or diagram portraying the software to Ann. Dimensions: 690px by 200px

Required Sections

The README.md is set up as follows. Each new section is marked (markup language) with ##. Please follow the order.

# Software name [mandatory]
example: # Helgoland

## Description [mandatory]

This section contains the following information:

Slogan: phrase describing what the software enables
[H1] example: ### Visual exploration and analysis of Sensor Web data

Short description: 1 – 2 short sentences highlighting what the software can do (from a marketing/user perspective)

[Paragraph Bold] example: ** This lightweight web application enables the exploration, analysis and visualization of sensor web data in various fields of use, e.g. hydrology, meteorology, environmental monitoring, traffic management. **

More detailed description: e.g. what can you do with the software

### Features [mandatory]

[H3] Marketing features. These should be listed with bullet points.

## Quick Start [mandatory]

How to install the software, i.e. installation and configuration. If you link to a wiki page for example, please provide a short description and then the link. See conventions below.

## User guide [mandatory]

User guide/tutorial If you link to a wiki page for example, please provide a short description and then the link. See conventions below.

## Demo [mandatory]

Please provide a screen shot and a short description of what is demonstrated or what you can try out with the demo as well as the link. Add any pertinent information about sample data.

## Changelog [mandatroy]

If linking to your Release notes, please provide an introduction – e.g. The latest changes, updates, bug fixes can be found in the Release notes...

## References [mandatory]

e.g. Project references, customer solutions. Please provide a brief introduction, e.g. the software is being used by the following organizations… The software is in operational use by… The following organizations implement…

## Credits [optional]

Developers, Funding projects, etc...

## Contribute [optional]

How to contribute. How to get involved.

## Contact [mandatory]

Name of person who is the code manager

## Download [mandatory]

Please provide a link to the release page.

## License [mandatory]

The software XY is licensed under the OS XY License. Any exceptions should be noted here. Include a link to the NOTICE file for dependencies.

Elements not supported

These elements are not supported and thus should not be used in the README.md.

• Emojis
• GitHub-specific markdown syntax for rendering icons like this ℹ️ using :information_source:
• numbered/ordered list.

README.md Conventions

• Do not link to other elements within the same page. #mein-Anker won't work on the home page.
• The section cannot be a link. Provide a screen shot/graphic and a description (more than one sentence). Then the link.
• Images: you must include an absolute link to the raw variant (raw path) not a relative path.
• Use markdown syntax (also for lists).

How to publish on the website

The WordPress workflow is as follows

• Create Software Project "Page"
• Fill Excerpt - one sentence - for the Software Overview Page
• Copy Visual Composer Code
• Fill in JSON configuration
• Fill in Software Release Box with information including GitHub, binary release, forum/Mailing list release,
• Fill in Content Box with information about License. The information should be included in the README.md and LICENSE file in the repository. Any exceptions should be noted here. Include a link to the NOTICE file for dependencies.
• Send screen shot, image, graphic for the "featured image" (it appears on the Software page) to Ann. Format is landscape, 690 px X 200 px.
• Set featured image.
• Fill in Contact Box with "connecion_id" of code manager.

CONTRIBUTING.md

• Extensions (Backends, etc., z.B. SOS )
• Road Map/development plans (features, focus…)
• Architecture/Design
• JavaDoc
• XML Schemata
• Contributors
• Requirements