wiki:How to document a project

Version 6 (modified by camerons, 7 months ago) (diff)

--

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:

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.