wiki:How to document a project

Version 12 (modified by bakaniko, 2 months ago) (diff)

--

Each project in OSGeoLive has to have a Project Overview, a Quickstart, and a section within our Lightning Presentation. You can find more information on the dedicated wiki pages about Overviews and Quickstarts. :

The information for the presentation is extracted from projects_info.csv

Build documentation can be found at:

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

Images

Images are stocked in a specific folder: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects

To create a new project, create a new folder here with slug of your project. As the screenshot and the logo image will be use automatically to build the overview page, be careful with their name.

Please use a slug that you can create following directions in How to configure a project documentation.

Locally, on your computer, it should be like this: doc/images/projects/<slug>/

The image folder of the GDAL project can be used as a reference.

Please note that images have to be in the png format.

The following section details specific indications about those images. The logo and the screenshot are used in several parts (Overview, Quickstart, Presentation) that are automatically build. These instructions must be followed carefully to unsure that the documentation is correctly build.

The project's logo is used in the headers of documentation (like Project Overviews, QuickStarts?, the presentation etc, and as icons on the OSGeoLive desktop.

Header logo:

optipng -o5 image.png

For example, for gvSIG, the project slug is: gvsig so the logo is doc/images/projects/gvsig/logo_gvsig.png

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

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

Project logos are stock in the images folder of the OSGeolive-doc folder following this path: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects and are stocked in the project folder.

So if you want to change/update your project logo, just change the file there and that's it. Please call it logo_<your-project-slug>.png so the program can find it.

It should be like this: doc/images/projects/<slug>/logo_<slug>.png

Screenshot

Project Overviews include an image, which is usually a screenshot, or collage of screenshots.

Quickstarts include screenshots for each significant step.

How to name and store your screenshot

  • Images must be stored here, in a dedicated folder, https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects
  • For the automated process of building the documentation, we need you to call your screenshot image like this: <your-project-slug>_screenshot.png.
  • for the screenshot present in the overview, it should be like this stored: doc/images/projects/<slug>/<slug>_screenshot.png

Note that the main screenshot used for the overview needs to be called <your-project-slug>_screenshot.png but other screenshots can be named as you want but must keep the <project-slug>_ prefix.

Screenshots size and format

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