Changes between Version 11 and Version 12 of How to document a project


Ignore:
Timestamp:
28 Aug 2020, 12:54:30 (4 years ago)
Author:
bakaniko
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • How to document a project

    v11 v12  
    1 For projects on OSGeoLive, we include a Project Overview, a Quickstart, and a section within our [https://live.osgeo.org/en/presentation.html#/ Lightning Presentation].
    2 
    3 Documentation can be found at:
     1Each project in OSGeoLive has to have a Project Overview, a Quickstart, and a section within our [https://live.osgeo.org/en/presentation.html#/ Lightning Presentation].
     2You can find more information on the dedicated wiki pages about Overviews and Quickstarts. :
     3
     4* [https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20the%20overview%20file]
     5* [https://trac.osgeo.org/osgeolive/wiki/How%20to%20document%20the%20quickstart%20file]
     6
     7The information for the presentation is extracted from [https://github.com/OSGeo/OSGeoLive-doc/blob/master/projects_info.csv projects_info.csv]
     8
     9Build documentation can be found at:
    410* Stable Release: https://live.osgeo.org
    5 * On OSGeoLive: http://localhost/ which is stored in /var/www
     11* On OSGeoLive disc and VM: `http://localhost/` which is stored in `/var/www` and opened want you launch Firefox
    612* Stable Release: https://live.osgeo.org
    713* Nightly Build: http://adhoc.osgeo.osuosl.org/livedvd/docs/en/index.html TBD: As of May 2019, this hasn't been updated for a while, and points to an old release.
    814* Build process: https://github.com/OSGeo/OSGeoLive-doc/blob/master/README.rst
    915
    10 The following sections describe components required OSGeoLive docs, and how to create/update them:
    11 * [[How to configure a project documentation]]
     16The following sections describe components required by OSGeoLive docs, and how to create/update them:
     17* [[How to configure a project documentation]] by filling `projects_info.csv`
    1218* [[How to document the overview file]]
    1319* [[How to document the quickstart file]]
    1420* How to update [[Glossary terms]]
    1521
     22== Images ==
     23
     24Images are stocked in a specific folder: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects
     25
     26To 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.
     27
     28Please use a slug that you can create following directions in [[How to configure a project documentation]].
     29
     30Locally, on your computer, it should be like this: `doc/images/projects/<slug>/`
     31
     32The [https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects/gdal image folder] of the GDAL project can be used as a reference.
     33
     34Please note that images **have to be** in the png format.
     35
     36The following section details specific indications about those images.
     37The logo and the screenshot are used in several parts (Overview, Quickstart, Presentation) that are automatically build.
     38These instructions must be followed carefully to unsure that the documentation is correctly build.
     39
    1640[[PageOutline(1-2)]]
    1741
    18 = Logo =
    19 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.
     42== Logo ==
     43
     44The project's logo is used in the headers of documentation (like Project Overviews, QuickStarts, the presentation etc, and as icons on the OSGeoLive desktop.
    2045
    2146Header logo:
    … …  
    3055}}}
    3156
     57For example, for gvSIG, the project slug is: `gvsig` so the logo is  `doc/images/projects/gvsig/logo_gvsig.png`
     58
    3259* Preferably also available as SVG, stored as "logo-<project>.svg"
    3360
    34 ;Desktop logo:
    35 : TBD: What are our requirements for desktop logos. Old docs suggested they might be:
    36 :* A 32x32-pixel XPM icon for use by the Debian menus
    37 :* A 48x48-pixel PNG icon for use by freedesktop.org menus
    38 
    39 = Screen Shot =
    40 Project Overviews include an image, which is usually a screenshot, or collage of screenshots. Quickstarts include screenshots for each significant step.
    41 * Images are to be stored here: https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects/<project>/
    42 * The Project Overview image is to be named <project>_screenshot.png
    43 * Screenshots should be taken from a 1024x768 display and should be created in PNG format.
     61=== Desktop logo ===
     62
     63{{{#!comment
     64TBD: What are our requirements for desktop logos.
     65}}}
     66
     67Old docs suggested they might be:
     68* A 32x32-pixel XPM icon for use by the Debian menus
     69* A 48x48-pixel PNG icon for use by freedesktop.org menus
     70
     71=== Update project logo ===
     72
     73Project 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.
     74
     75So 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.
     76
     77It should be like this: `doc/images/projects/<slug>/logo_<slug>.png`
     78
     79
     80== Screenshot ==
     81
     82Project Overviews include an image, which is usually a screenshot, or collage of screenshots.
     83
     84Quickstarts include screenshots for each significant step.
     85
     86=== How to name and store your screenshot ===
     87* Images must be stored here, in a dedicated folder, [https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/images/projects]
     88* For the automated process of building the documentation, we need you to call your screenshot image like this: {{{<your-project-slug>_screenshot.png}}}.
     89* for the screenshot present in the overview, it should be like this stored: `doc/images/projects/<slug>/<slug>_screenshot.png`
     90
     91Note 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.
     92
     93
     94=== Screenshots size and format ===
     95
     96* Screenshots should be taken from a '''1024x768''' display and should be created in '''PNG format'''.
    4497* Screenshots can be taken using [http://shutter-project.org/ Shutter] (on linux) or [http://getgreenshot.org/ Greenshot] (on windows).
    4598* 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.
    … …  
    47100* For PNGs run a program like [http://packages.ubuntu.com/pngcrush pngcrush] to reduce the size of the image without degrading quality.
    48101
     102{{{#!comment
    49103= project_info.csv =
    50104The [https://github.com/OSGeo/OSGeoLive-doc/blob/master/projects_info.csv project_info.csv] config table defines which projects are included in OSGeoLive docs during the doc build process.
    … …  
    150204* `Y` : project included the ISO (default value)
    151205* `N` : project included the VMDK only
     206}}}