wiki:Contribute/Documentation

Version 62 (modified by thiloshon, 9 years ago) ( diff )

--

Contribute: Documentation

These task are great for people who are good at writing clear documentations or thorough at reviewing and editing existing documentation. As this is a software project, you may need some technical expertise for some of the projects.

Easy

Update Wiki [GCI, multiple tasks]

Added to GCI spreadsheet

  • Review the flow & navigability of the wiki and send an email to the groups.google.com/group/sahana-eden list with any improvements that you would like to make. Have a look at the TitleIndex -- you'll see User..., Developer..., Blueprint... pages arranged oddly, and some pages with no general topic.
  • Recently Sahana Eden implemented new Template functionality which made the "deployment_template" folder redundant. Remove or update all historic references to the "deployment_template" folder from the Sahana Eden wiki and Book.
  • Recently Sahana Eden migrated from using bzr on Launchpad to git on Github (DeveloperGuidelines/Git). Remove or update all out-of-date references to bzr and Launchpad on the Sahana Eden wiki and Book.

Test Developers Installation Documentation for Windows [GCI]

Added to GCI spreadsheet
Follow the documentation on http://eden.sahanafoundation.org/wiki/InstallationGuidelines to install a developer's instance of Sahana Eden on your Windows OS. Once you have completed send an email to the groups.google.com/group/sahana-eden list stating:

  1. Summary of the exact steps you tool
  2. Screenshots of Sahana Eden installed on your OS
  3. How long it took you?
  4. What was the most difficult part?
  5. 3 improvements you would like to make - these need to be as specific as possible - does content need to be added? Clarified? Simplified? Is there a need for pictures (of what?)?. Ideally you will edit the documentation on the Wiki to make these improvements yourself.
  6. Any other questions you may have about Sahana Eden

Test Developers Installation Documentation for Mac [GCI]

Added to GCI spreadsheet
Follow the documentation on http://eden.sahanafoundation.org/wiki/InstallationGuidelines to install a developer's instance of Sahana Eden on your Mac OS. Once you have completed send an email to the groups.google.com/group/sahana-eden list stating:

  1. Summary of the exact steps you tool
  2. Screenshots of Sahana Eden installed on your OS
  3. How long it took you?
  4. What was the most difficult part?
  5. 3 improvements you would like to make - these need to be as specific as possible - does content need to be added? Clarified? Simplified? Is there a need for pictures (of what?)?. Ideally you will edit the documentation on the Wiki to make these improvements yourself.
  6. Any other questions you may have about Sahana Eden

Test Developers Installation Documentation for Linux [GCI]

Added to GCI spreadsheet
Follow the documentation on http://eden.sahanafoundation.org/wiki/InstallationGuidelines to install a developer's instance of Sahana Eden on your Linux OS. Once you have completed send an email to the groups.google.com/group/sahana-eden list stating:

  1. Summary of the exact steps you took
  2. Screenshots of Sahana Eden installed on your OS
  3. How long it took you?
  4. What was the most difficult part?
  5. 3 improvements you would like to make - these need to be as specific as possible - does content need to be added? Clarified? Simplified? Is there a need for pictures (of what?)?. Ideally you will edit the documentation on the Wiki to make these improvements yourself.
  6. Any other questions you may have about Sahana Eden

Test Developers Installation Documentation for Amazon EC2 [GCI]

Added to GCI spreadsheet
Follow the documentation on http://eden.sahanafoundation.org/wiki/InstallationGuidelines to install a developer's instance of Sahana Eden on Amazon EC2.

GCI students: Before you choose this task: This requires getting an Amazon AWS account. Although your first EC2 "micro" instance is free for a year, you'd be "using up" your free instance, and you might want to leave that for real use later. Also, the AWS account registration requires a credit card with permission to for online use.

Once you have completed send an email to the groups.google.com/group/sahana-eden list stating:

  1. Summary of the exact steps you took
  2. Screenshots of Sahana Eden installed on Amazon EC2
  3. How long it took you?
  4. What was the most difficult part?
  5. 3 improvements you would like to make - these need to be as specific as possible - does content need to be added? Clarified? Simplified? Is there a need for pictures (of what?)?. Ideally you will edit the documentation on the Wiki to make these improvements yourself.
  6. Any other questions you may have about Sahana Eden

Test Customization Documentation [GCI]

Added to GCI spreadsheet
Follow the documentation on http://en.flossmanuals.net/sahana-eden/customisation/ to customize your local instance of Sahana Eden. Once you have completed send an email to the groups.google.com/group/sahana-eden list with:

  1. Screen Shots of your customized module
  2. How long it took you?
  3. What was the most difficult part?
  4. 3 improvements you would like to make - these need to be as specific as possible - does content need to be added? Clarified? Simplified? Is there a need for pictures (of what?)?. Ideally you will edit the documentation on the Wiki to make these improvements yourself.
  5. Any other questions you may have about Sahana Eden

Test Building a New Module Documentation [GCI]

Added to GCI spreadsheet
Follow the documentation on http://en.flossmanuals.net/sahana-eden/building-a-new-application/ to customize your local instance of Sahana Eden. Once you have completed send an email to the groups.google.com/group/sahana-eden list with:

  1. Screen Shots of your new module
  2. How long it took you?
  3. What was the most difficult part?
  4. 3 improvements you would like to make- these need to be as specific as possible - does content need to be added? Clarified? Simplified? Is there a need for pictures (of what?)?. Ideally you will edit the documentation on the Wiki to make these improvements yourself.
  5. Any other questions you may have about Sahana Eden

Add Screen Shots to Building a New Module Documentation [GCI]

Added to GCI spreadsheet
Follow the documentation on http://en.flossmanuals.net/sahana-eden/building-a-new-application/ to customize your local instance of Sahana Eden. Once you have completed send an email to the groups.google.com/group/sahana-eden list with:

  1. Screen Shots of your new module. You will need to take the relevant sections of these screen shots and add them into the Book as examples
  2. How long it took you?
  3. What was the most difficult part?
  4. 3 improvements you would like to make - these need to be as specific as possible - does content need to be added? Clarified? Simplified? Is there a need for pictures (of what?)?. Ideally you will edit the documentation on the Wiki to make these improvements yourself.
  5. Any other questions you may have about Sahana Eden

Intermediate

Update and Rearrange the Standards Wiki [GCI]

Added to GCI spreadsheet

  • Review the flow & navigability of the Standards wiki
  • Send an email to standards at sahanafoundation dot org with any improvement you would like to make
  • Goals are to make wiki more presentable and give users easier access to information.

Prepare data model relationship entity diagram for each module in Sahana Eden

Can use MySQL workbench to reverse-engineer the Eden database into an ERR diagram, then tidy up to show the actually important information for developers (e.g. hide meta-fields, auth references and similar, annotate the foreign keys for links, move objects so they don't overlap too much), for an example see http://pub.nursix.org/eden/err_model.png.

Write blueprint to add transliteration to text entry controls

Proposed by: | Nuwan
Specific : For local language text entry one can use a native language keyboard with native unicode character set or use transliteration to allow entering the native word phonetically. for example with | Google Transliteration Beta or other plug-in like [ http://www.ucsc.cmb.ac.lk/ltrl/services/feconverter/t1.html | USCS's Real-Time Unicode Converter]
Measurable : Users in Sri Lanka, for example, prefer Sinhala or Tamil languages. Making the option for them to turn on transliteration in Sahana to enter critical information in the local language is an important usability aspect.
Attainable :
Step 1 :: research the available Python/web2py transliteration engines
Step 2 :: trial/experiment with each one to determine the best
Step 3 :: develop a set of recommendations for embedding a generic transliteration engine in Eden
Step 4 :: discuss the recommendations with Sahana community
Step 5 :: document the specifications for developing the agreed on transliteration functionality
Relevant : In community-based disaster management literacy skills including English is poor. Important to develop flexible usable software for inclusiveness
Time-bound : No more than a few days to research the Internet. Another several days to discuss and finalize on the design specifications. Evaluate : The recommended design would be discussed by the community to evaluate its workability.
Reevaluate : Validate the final specifications document.

Write/Update User Guidelines for a Module

Write generic User Guidelines wiki page for a Sahana Eden module. The page should be located at UserGuidelines/<Module>/<Workflow>. The documentation should adhere to the following outline:

start of outline

== <Title of the Module> User Guidelines ==
=== Introduction ===
<Description of the module. Where possible include some sort of flow chart or diagram. This should be designed using Google Draw and embedded in the wiki page. Include the link to the Google Draw file so that others can edit it >
=== Data Model ===
<a list of the tables that the user can access in the module>

=== Reports ===
The reports that the user can generate and a brief explanation about them

=== Workflows ===
<links to workflows for that module (you do not need to complete the documentation for all of these workflows)>

end of outline

List of Modules to document:

  • Staff
  • Volunteers
  • Assets
  • Organisations
  • Requests
  • Inventory / Warehouse
  • Projects

Ensure that you review and merge any current UserGuidelines.

Write/Update User Guidelines for a Workflow

Write generic User Guidelines wiki page for a workflow for a Sahana Eden module. The page should be located at UserGuidelines/<Module>/<Workflow>. (See the end of this task for details of adding the wiki page.) GCI students: (With a few accidental exceptions) your task has the name of a specific module and workflow -- that prevents wasted effort on duplicate pages. If your task does not have the module and workflow specified in its name, please check TitleIndex and the names of tasks on Melange to choose one that is not done or being worked on.

The documentation should adhere to the following outline:

start of outline

== <Title of the workflow> ==
=== Introduction ===
<basic purpose of the workflow>
=== Details ===
<step by step description of the workflow. Where possible include some sort of flow chart or diagram. This should be designed using Google Draw and embedded in the wiki page. Include the link to the Google Draw file so that others can edit it >
=== Screenshots ===
<thumbnails of each stage, clickable to see full size>
=== Related Workflows ===
<links to related workflows>

end of outline

List of potential workflows:

  • Warehouse
    • Send shipment
    • Receive shipment
    • Adjust stock levels
    • Request stock
  • Staff & Volunteers
    • add volunteer
    • add volunteer address & contact details
    • add volunteer's education & trainings
  • Project
    • create project
    • add communities and beneficiaries to project
    • add staff & volunteers to project
    • add budget and produce funding report

For further information:

How to add the new workflow wiki page:

  • Register for a wiki account.
  • Go to the URL for the wiki page you want to create. The general form is: http://eden.sahanafoundation.org/wiki/UserGuidelines/<Module>/<Workflow>
  • <Module> and <Workflow> are the names of the module and workflow you selected, in "CamelCase". That is, capitalize all words, remove all spaces and punctuation. For instance, for module Staff & Volunteers and workflow add volunteer's education & trainings, this would be: http://eden.sahanafoundation.org/wiki/StaffVolunteers/Warehouse/AddVolunteersEducationTrainings

Generate example CAP messages

Proposed by: | Nuwan

  • If you haven't already, register as a Sahana Eden demo user
  • Access the Sahana Eden CAP Broker
  • Follow the guide to understand the objectives of the CAP Broker and how it should be operated
  • Choose a type of disaster or emergency. GCI students: Look at the table at the end of this task to see which have already been chosen -- select something not already there. As soon as you choose, edit this wiki page section and add your choice on a new line, with your name or nickname.
  • Create a hypothetical scenario or search for a previous event on the web to establish a natural or human-instigated hazard event such as a recent earthquake, cyclone, landslide, epidemic, etc; gather up all the details; i.e. exact locations, times, dates, responsible organizations for detecting the event, then issuing the alert, so on and so forth
  • Create an abstract template for the hazard event of your choice. The template should not use actual LOCATION names or DATES, instead in the description and headline you should use place holders such as LOCATION and YYYY-MM-DD.
  • Create a CAP message for the hypothetical or passed event using the template; the message should carry information related to all mandatory elements, be descriptive for any human to understand, reference any additional information, clearly specify dates, times, etc. Place holders such as LOCATION and YYYY-MM-DD should be replaced with actual locations and dates.

GCI students: When you choose a scenario, add it here on a new line, along with your name or nickname.
After the examples are approved, upload the CAP template and CAP message files exported as XML, CSV or JSON and place the links in the table below.

Example No. Disaster Scenario template file message file
0 heat wave template_alert msg_alert, msg_info, msg_area
1 Fire Information Entries,Area
2 Earthquake template_alert Information Entries, | Alert]
3
4
5

Advanced


Contribute

Note: See TracWiki for help on using the wiki.