wiki:How to document a project

Version 10 (modified by flicstar, 5 years ago) ( diff )

Added link to build process readme

For projects on OSGeoLive, we include a Project Overview, a Quickstart, and a section within our Lightning Presentation.

Documentation can be found at:

The following sections describe components required OSGeoLive docs, and how to create/update them:

  1. Logo
  2. Screen Shot
  3. project_info.csv
    1. document
    2. slug
    3. version
    4. Quickstart?
    5. Overview?
    6. Classification
    7. last
    8. One Liner
    9. OpenHub name
    10. URL
    11. kind
    12. name

Logo

The project's logo is used in the headers of documentation (like Project Overviews, QuickStarts, Powerpoint presentations etc, and as icons on the OSGeo-Live Desktop.

Header logo: 

optipng -o5 image.png
  • Preferably also available as SVG, stored as "logo-<project>.svg"

;Desktop logo: : TBD: What are our requirements for desktop logos. Old docs suggested they might be: :* A 32x32-pixel XPM icon for use by the Debian menus :* A 48x48-pixel PNG icon for use by freedesktop.org menus

Screen Shot

Project Overviews include an image, which is usually a screenshot, or collage of screenshots. Quickstarts include screenshots for each significant step.

  • Images are to be stored here: ​https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects/<project>/
  • The Project Overview image is to be named <project>_screenshot.png
  • Screenshots should be taken from a 1024x768 display and should be created in PNG format.
  • Screenshots can be taken using ​Shutter (on linux) or ​Greenshot (on windows).
  • For Quickstarts, consider marking up the image to explain the current steps. Eg: Add circled numbers: 1, 2, 3 or draw an oval around buttons being described. This is very easy to do using the "Edit" tab in the Shutter program, which provides these drawing icons to add. Tutorials augmented with detailed and pertinent images make it easy for the reader to follow what is going on. Extra time spent on an image pays off big in comprehension (you need more than just a course screen dump). Lines, numbering, highlights, boxes and annotations all help direct a user's focus to those areas which are important.
  • Screenshots with large areas of constant color (menus, etc.) should be in PNG format, screenshots containing large areas of imagery (satellite images, shaded relief DEMs, etc.) should be in JPEG format.
  • For PNGs run a program like ​pngcrush to reduce the size of the image without degrading quality.

project_info.csv

The ​project_info.csv config table defines which projects are included in OSGeoLive docs during the doc build process.

Each project has a dedicated row with metadata and variables, with fields separated by the pipe | symbol. Rows starting with a hash # symbol are comment rows. Rows have been organised into categories, and new projects should be inserted into the correct category.

Note: Documentation for a new project should only be enabled with oversight from the OSGeoLive Project Steering Committee.

The purpose of fields is described below. 

# document? | slug |version| Quickstart? |Overview?|Section| last | One Liner| OpenHub name |URL|kind|name

document

Add Y if the project documentation should be built.

If the project has been retired, change to N and move the row to the retired section.

slug

Page name used to construct logo-<slug>.png <slug>_screenshot.png <slug>_overview.rst etc. Page name can contains dashes, underscore, numbers or capital letters but no spaces.

Examples:

  • pgRouting is the real name of the project but the page name is pgrouting
  • User-friendly Desktop Internet GIS is the real name of the project but udig is the page name
  • it gives: udig_overview.rst udig_quickstart.rst logo-udig.png udig-screensot.png

version

The project's software version.

Examples:

  • 2.14.14 for QGIS 2.14.14
  • 4.3.0a for 4.3.0 alpha release of Spatialite

Quickstart?

Add Y if the documentation should build a quickstart page for this project, N if it shouldn't.

Overview?

Add Y if the documentation should build an overview page for this project, N if it shouldn't.

Classification

Select from one of the existing categories listed here. These categories are used for grouping projects in documentation and presentation.

Desktop GIS | Browser Facing GIS | Web Services | Data Stores | Navigation and Maps | Spatial Tools | Domain Specific GIS | Data | Geospatial Libraries

last

Used only for deprecated / removed projects and contains the last version of OSGeoLive when the project was installed on OSGeoLive.

One Liner

One line description that goes after the quickstart link in the Overview page.

OpenHub name

OSGeoLive's metrics page presents ​OpenHub metrics to help users assess the maturity of projects.

Provide the OpenHub name.

For example: This is the link to OpenHub for pgRouting: ​https://www.openhub.net/p/pgrouting

Then the OpenHub name is pgrouting

URL

Insert the URL of the project's homepage.

kind

Your OSGeo project categorisation, as per ​https://www.osgeo.org/projects/ . If associated with OSGeo, the corresponding OSGeo icon will be added to your project pages under the project logo.

Parameters:

  • OSGeo_community
  • OSGeo_project
  • OSGeo_incubation
  • blank

name

Complete name of the project respecting the case (unlike slug).

For example pgRouting (slug is pgrouting)

Note: See TracWiki for help on using the wiki.