inasafe / inasafe-doc Goto Github PK

Documentation project for InaSAFE

Shell 62.34% Nix 33.67% Dockerfile 3.99%

inasafe-doc's Introduction

InaSAFE

InaSAFE is free software that allows disaster managers to study realistic natural hazard impact scenarios for better planning, preparedness and response activities. InaSAFE is a plugin for QGIS.

For more information about InaSAFE and its documentation please visit inasafe.org.

The latest source code is available at https://github.com/inasafe/inasafe, which contains modules for risk calculations, GIS functionality and functions for impact modelling.

Current Travis test status master:
Current Landscape code health master:
Current Travis test status develop:
Current Landscape code health develop:
PyPi Downloads for InaSAFE:
PyPi Downloads for the old 'safe' library (currently unmaintained):
Github download:

Quick Installation Guide

You first need to have QGIS installed. Grab your free copy from the QGIS download page.

To install the InaSAFE plugin, use the plugin manager in QGIS:

Plugins → Manage and Install Plugins

Then search for "InaSAFE", select it and click the install button. The plugin will now be added to your plugins menu.

Note: You may need to restart QGIS if upgrading from a prior version.

Participation

We work under the philosophy that stakeholders should have access to the development and source code, and be able to participate in every level of the project - we invite comments, suggestions and contributions. See our milestones list and our open issues list for known bugs and outstanding tasks. You can also chat live with our developers and community members using the link below.

System Requirements

A standard PC with at least 4GB of RAM running Windows, Linux or Mac OS X
The QGIS Open Source Geographic Information System (http://www.qgis.org). Although InaSAFE will probably run on any version of QGIS version above 2.0 or newer, our supported version is the latest Long Term Release version of QGIS.

Running tests

InaSAFE is using the Unittest Python framework.
Different ways that you can run tests:
- On Travis using a Pull Request
- In QGIS Desktop if you enable developer mode in Plugins -> InaSAFE -> Options -> Advanced, restart QGIS and then click the run tests button.
- Using docker make docker-test
- Using PyCharm if you set up the dev environment with the qgis_prefix_path

History

In March 2011, Risk In A Box (the predecessor to InaSAFE) was built as a web application running as a GeoNode Plugin.
InaSAFE development as a QGIS plugin started in January 2012.
In October 2012, version 1.0 of InaSAFE was launched at the 5th Asian ministerial conference on disaster risk reduction (AMCDRR) where it was demonstrated to the then president of Indonesia, Susilo Bambang Yudhoyono who praised the project.
On 30 Jan 2013, InaSAFE was awarded the prestigious Black Duck Open Source Rookie of the Year Award.
Version 2.0 of InaSAFE was released in January, 2014.
Version 3.0 was released in March 2015 which added support for using the QGIS API within impact functions.
Version 4.0 was released in March 2017.
Version 5.0 was released in November 2018 which add support for QGIS 3.x

Disclaimer

InaSAFE has been jointly developed by the Indonesian Government-BNPB, the Australian Government, the World Bank-GFDRR and independent contributors. These agencies and the individual software developers of InaSAFE take no responsibility for the correctness of outputs from InaSAFE or decisions derived as a consequence.

License

InaSAFE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 (GPLv3) as published by the Free Software Foundation.

The full GNU General Public License is available in LICENSE.txt or http://www.gnu.org/licenses/gpl.html

Disclaimer of Warranty (GPLv3)

There is no warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.

Limitation of Liability (GPLv3)

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who modifies and/or conveys the program as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.

inasafe-doc's People

Contributors

Stargazers

Watchers

inasafe-doc's Issues

inasafe_projects.rst with no content

Problem

Found another file with nearly no content

I'll attach the content here to have it available::

Demo projects

The |project_name| project comes with bundled demonstration data and a
collection of QGIS projects that demonstrate different use cases:

Taking this out for now because it's only one sentence.

Developer docs should not be included in translations

Problem

We (Kristy, Tim, Ismail) have discussed whether it is a good idea for the developer docs to be translated to Bahasa and our conclusion is that they should remain in english.

Proposed solution

Remove all developer docs resources from .tx/config
Remove all developer docs from transifex
Update scripts that generate transifex resources to exclude dev docs
Update scripts that extract strings from docs to exclude developer docs

Expected outcome

Developer docs should not show as translatable

We need to migrate the content from learnosm.org

Problem

The training resources used in training courses are not consolidated in one documentation tree. This makes for a less professional looking product where everything could be consistently styled and indexed, and probably is more confusing for trainees who need to keep track of multiple resources to remember 'where did I learn that'?

Proposed solution

We first need an investigation phase - ideally the learnosm resource should continue to exist independently and we should regularly be able to 'harvest' its content and incorporate that into the inasafe-doc tree.

Expected outcome

All documentation related to InaSAFE should be available in one comprehensive documentation set.

RFC New Documentation Webpage Theme evaluation

Problem

As the Logo of InaSAFE has changed for the upcoming Version 1.2 we have to adjust the theme in the Webpage according to the new logo colours

Proposed Solution

I already made a commit and uploaded it .. Jenkins build runs fine and the webpage gets published at http://inasafe.linfiniti.com/en/ for you to have a look at

Outcome

Just have a look and tell me if it is fine that way or where I should adjust some things.

QGIS 2.0 needs translation into Bahasa Indonesia

Problem

We need to ensure that when QGIS 2.0 comes out it is fully translated into Bahasa Indonesia

Proposed solution

@mach0 to update QGIS strings in master
send .ts file to Trias Aditya
when QGIS 2.0 is string frozend ask them return the .ts file
update the ts file again and send back to Trias for finalisation of strings
get the .ts file back in time for final incorporation into QGIS 2.0

Expected outcome

QGIS 2.0 should ship with 100% translation. AUSAID is providing the resources to make this happen, we need to coordinate it.

CC

@vanpuk

Extending documentation

Problem

As the functional documentation is completely reworked and restructuring
I found

Things to cover (suggested by Trias Aditya)

access to statistics data
access to WFS (for exposure data)
access to WMS (for background data)
you have got an idea to access WCS (e.g. hazard, elevation data etc)
map the projected impact into graphical charts (this will be my
favourites then...)

in using_qgis.rst under user-docs
keeping it here for reference and ask Trias what he meant with this .. At hat place it does not fit and I delete it from there to be hidden to public audience.

Solution

Find a place and write the documentation for the suggested topics
The link to this github issue will be mailed to trias by me. Would be nice if he has some time to cover his topics himself and provide it.

Tutorial and context need to be placed properly into the docs tree

Problem

There are two files 'context.rst' and 'tutorial.rst' in the top level of the inasafe-doc repo. These are not compiled into the sphinx output and are otherwise ignored.

Proposed solution

Move the docs mentioned above into an appropriate place in the docs source tree or remove them if they are redundant.
Check they compile without introducing any new errors
Ensure they are part of a logically consistent section in the docs

Expected outcome

Stray files are cleaned up
Important content is not lost from the rendered documentation

CC

@vanpuk

IRC page help text needs review

Problem

The text on IRC needs to be improved

Proposed solution

Old:

Ask your question without asking to ask.
Be patient. There is not always someone around at the very same second answering your question.
Wait for some time. Your message is readable for other users that are inside the chat. It might take a bit to answer you question too.

New:

There is no need to ask if it is ok to ask your question, we encourage any and all questions.
Be patient. Other members of the chat room may be busy with other work or have stepped away from the computer. Just log in to the channel and say hello and wait for some activity.
Keep the chat window open - even if someone replies to you they may be busy with other work so the replies may not always be instantaneous.

Old:

Expected outcome

Users can easily understand the text displayed on the page.

We need an RFC section in the documentation

Problem

We need a way to formalise the process large architectural changes to the code base.

Proposed solution

@vanpuk and @timlinux will put together a proposed RFC template. This should be added to the documentation tree.
When a developer or organisation wants to implement a large scale change to the code base we will request that they first complete the RFC document.
All RFC's should be numbered sequentially and written in RST/Sphinx markup.
A new section needs to be added to the documentation tree (care of @mach0) for RFC's. This would contain both the template and then all of the existing RFCs in sequential order.

Note: It is not my proposal that RFC's should be required for everyday tasks, only for large API upheavals (e.g. switching to QGIS 2.0 api).

Expected outcome

We have complete provenance of all the decisions made leading up to major changes in the project and a rigorous approach to the incorporation of new ideas that may lead to major changes in the code base.

rst files with no content

Problem

I found a lot of more or less empty files inside the user-docs folder
specifically:
beginning_spatialdata_alalysis_docs and
inter_spatialdata_analysis_docs

There are numbered files into them beginning with 01_introduction ... 02_ 03_ ...

I just wanted to know if these files are abandoned files or if there is some work going on to fill them with content.

maybe @emirhartato also knows something about that files
they were initially created by @vasanthi0808

Could somebody please enlighten me in that case?
thanks a lot
Werner

We need to ensure logo does not wrap

Problem

Logo wraps on 1024x768 display

Proposed solution

Adjust css to ensure logo always stays on the same line as the menu?

Expected outcome

The page should look good at 1024 width

Get the reworked Documentation translated and fixed with sphinx function

Problem

The whole Documentation is being reworked and extended with sphinx functionality.
The Translation should keep up with the original Documentation.

Proposed solution

Go through every rst file and translate it and rework the added sphinx functionality.

Expected outcome

Clean and functional Documentation in every language we provide (currently only en and id).

For control i'll add every rst file starting from inasafe-doc/docs/source tree which is done in english language to be checked for indonesian

reworked | filename

nothing to do because there is no content right now

Generated out of python files typos need to be fixed in dev

user-docs/impact_function_docs/CategorisedHazardPopulationImpactFunction
user-docs/impact_function_docs/EarthquakeBuildingImpactFunction
user-docs/impact_function_docs/FloodBuildingImpactFunction
user-docs/impact_function_docs/FloodEvacuationFunction
user-docs/impact_function_docs/FloodEvacuationFunctionVectorHazard
user-docs/impact_function_docs/ITBFatalityFunction
user-docs/impact_function_docs/PAGFatalityFunction
user-docs/impact_function_docs/VolcanoBuildingImpact
user-docs/impact_function_docs/VolcanoPolygonHazardPopulation

Text on the front page needs to be edited

Problem

Text on the front page needs to be edited

Currently

The goal of InaSAFE is to create a tool that can provide rapid and relevant information in order to understand risk related to events such as volcanic eruptions, inundation from flood / tsunami, earthquakes and so on.

InaSAFE is a collaborative effort between the Australia Aid Agency in Indonesia, the BNPB (Indonesia), the World Bank-GFDRR, the Australia-Indonesia Facility for Disaster Reduction, Universitas Gadja Mada and other participating organisations.

Indonesian Scenario Assessment for Emergencies (InaSAFE) is a Free and Open Source Software (FOSS) project, published under the GPL V3 license. As such you may freely download, share and (if you like) modify the software.

Change

InaSAFE is free software that produces realistic natural hazard impact scenarios for better planning, preparedness and response activities. It provides a simple but rigorous way to combine data from scientists, local governments and communities to provide insights into the likely impacts of future disaster events.

InaSAFE was conceived and initially developed by the Indonesia’s National Disaster Management Agency (BNPB) and the Australian Agency for International Development, through the Australia-Indonesia Facility for Disaster Reduction, the World Bank - Global Facility for Disaster Reduction and Recovery (GFDRR).

IRC Chat Page needs translation

Problem:

With SHA: 224120b we now have a irc chat page which is technically very similar to the index page (it is also located in the same place: inasafe-doc/docs/templates
called irchat-id.html.
That would need the same amount of attraction to being translated as the index page itself

Solution

Would you please take some time and translate that page. Everything is already prepared and in place.

Enhancing

If you have suggestions for a better helping to the user you are very welcome to add it and probably also add it afterwards in the english page ..

We need an examples section in the documentation

Problem

Even when reading the docs, projective users really don't have a good idea of what InaSAFE will produce.

Proposed solution

Add a new top level section called 'examples' to the docs.
Create a new scenarios dir in docs english static folder and create one scenario (using the save scenario tool in InaSAFE) per impact function permutation.
Switch to bahasa and generate the same scenarios in the id static folder
Use the batch runner to generate a pdf product for each scenario into the scenarios dir
Create an index file in rst which lists (with hyperlinks to pdfs) all the scenarios along with a short description of what each does. There should be two links for each scenario - one for map and one for table

Note: Use the scenario data from the InaSAFE data packages it has sufficient data to test all impact functions.

Expected outcome

Visitors to our web site will be able to browse a gallery of nice InaSAFE generated pdfs showing the outcomes of the different impact functions
We should be able to regenerate these pdfs automatically (or semi automatically) as we improve reporting and add new impact functions.

CC

@vanpuk
@wonderchook

Switch to Bahasa Indonesia!

Problem

At the main Webpage there is the

Switch to Bahasa Indonesia!

written in English language ..
This can obviously not be understood by some people and should be written in Bahasa.

Proposed solution

Could you please translate that into Bahasa in the file index-en.html and commit that?

Expected outcome

People not understanding english and visiting the Webpage can easily read that sentence and switch to Bahasa.

We need to change references to AIFDRR to World Bank-GFDRR

A request from Abby Bacca (WB).

One small request in the areas on the website and the pdf reports where there is a reference to the supporting institutions, can this be changed to World Bank-GFDRR instead of just GFDRR?

We need clear and concise guidelines for documentation writers

Problem

As more people participate in our documentation project there is scope for wildly different documentation styles and a general degradation of the quality of our documentation.

Currently we have http://inasafe.linfiniti.com/en/developer-docs/maintaining_documentation.html which provides some basic info on how to write documentation but it is not adequate to fully orientate new documentors into our system.

Proposed solution

split http://inasafe.linfiniti.com/en/developer-docs/maintaining_documentation.html into two - one document for API documentation style guide, one section for user documentation style guide.
Ensure the API documentation guide is self contained with outward links to rst and user documentation where relevant.
For end user documentation, detail the key markup elements that should be used and other important aspects that should be taken care of when writing sphinx documentation.
Add a new section on the procedures needed to setup a host (initially targetted to linux only) so that it is possible to compile the documentation locally.

Expected Outcome

Providing clear guidelines and regularly auditing the documentation to ensure guideline compliance will prevent the documentation from losing quality over time

deleting tutorial.rst

I was told by Tim that I could delete the tutorial.rst from the documentation.

I just wanted to make sure that you are really comfortable with this and that there is no relevant information left in the tutorial that is not covered on other places.

So please confirm that I can just take away tutorial.rst

Organization Diagram

Problem

As the project has a lot of "connections" I am currently trying to start with an organization diagram / Organigram.
For that I would need the names, the position and the email address of all persons involved into the InaSAFE project.
I see a lot of people here connected to github with their nicknames but not all have their real names beside the login name and there is no description (developer/translator/team leader...) at all ..
The main reason is that I created a mailing domain for inasafe.org and we now have that [email protected] address which should be forwarded to more (at least 3) persons involved. Therefore I am currently searching for the email addresses of the responsible persons in all companies to get an foward mailaddress for [email protected].
That mail adress would be published at the bottom of the upcoming InaSAFE page:
"Contact [email protected] for more information." it has been Ole's mail address for a long while and I don"t know yet how much traffic will be there.

Solution

@wonderchook @emirhartato @vanpuk @timlinux
Would you please give me the Details who is currently involved in your company/organisation with the InaSAFE Project and which address I should put on the [email protected] "list".
I will also create a Diagram with yed which will show the connection between persons and companies and their responsibility.

Community registration site - deploy django people

Problem

Currently we have no idea of who and where our users are.

Proposed solution

Deploy a community registration site (purely optional for users) where users can describe themselves and their location. I propose we take something 'off the shelf' like this:

https://github.com/timlinux/djangopeople

We should fully automate this deployment using fabgis.

Expected outcomes

Users can show their association with the InaSAFE project.
InaSAFE managers can get a sense of what the uptake of our software is and relay this to decision makers and so on.
Users can locate other users nearby and form user communities.
During training courses, part of the curriculum could be to get course attendees to register (well walk them through the process and they can choose not to if they like), that way we could also get a picture of how many people have undergone training etc.

CC

@vanpuk
@wonderchook

IRC chat gives bad password error

Problem

When logging in to IRC channel we often get bad password errors:

Proposed solution

Investigate if this is a known issue with the irc web client

Expected outcome

Assuming the captha info is correct, the user should be able to log in successfully.

We need to get the latest doc updates pushed to transifex

Problem

We need to ship with up to date translation of context help.

Proposed solution

Yesterday I have made some more improvements to the doc used for context help - if would be great if the HOT team could translate these updates so we can ship the BI version with the release.

Werner to push to transifex
HOT Team to translate and approve
Werner to pull back to docs
Tim to package relevant docs into the plugin

Expected outcome

BI Users should have a great experience when using the context help in InaSAFE.

We should not include base classes and rc files in safe_qgis api docs

Problem

Currently we show documentation for Qt ui base classes - I don't think this adds any value. We also show tests in the API docs which don't really belong there.

Proposed solution

Remove all _base.rst, _rc.rst files from docs/source/api_docs/safe_qgis/
Remove all from docs/source/api_docs/safe_qgis_test
Remove all api-docs/safe/messaging/example
Update generator scripts to ensure they don't get added back in future
When updating the generator script add a note referencing this ticket where you exclude the above mentioned files.

Expected Outcome

Only relevant modules should be listed in the API docs.

CC

@vanpuk

We need to ensure that all documentation files have resources in Transifex

Problem

Currently many of the documentation rst resources do not show up in transifex and thus translations won't make their way back to the web site.

Proposed solution

Run the create transifex resource script and ensure that all resources are properly created.
Check that existing resources are not lost

Expected outcome

All rst files should be listed in transifex for translation
Running post translate should produce translated docs for as much of the documentation as possible

We need to rename the api docs generation scripts.

Problem

The file scripts/gen_rst_script.py and scripts/gen_impfunc_doc.py which are used to generate the api and function docs are poorly named, their purpose is not obvious.

Proposed solution

Rename the file and all references to it in:

documentation
other scripts
jenkins etc

Proposed new name: create_api_docs.py
Proposed new name: create_impact_function_docs.py

Expected outcome

The purpose of script should be obvious from the file names.

We need a good readme for documentors.

Problem

When arriving at the inasafe-doc repo, there is no obvious starting point

Proposed solution

On the QGIS-Documentation page we have a really nice 'getting started' readme for new document writers and translators. We should adapt this content to produce something similar for ourselves. See https://github.com/qgis/QGIS-Documentation

Expected outcome

New document writers will find the help the need to get started when they arrive at https://github.com/AIFDR/inasafe-doc

We need to investigate the cause of fuzzy strings

Problem

Certain strings do not appear in translated documentation outputs. It seems to relate to the presence of the 'fuzzy' gettext indicator e.g.

# 0e7f4bc362b14daf8c619b667e7700de
#: ../../source/user-docs/impact_function_docs/FloodBuildingImpactFunction.rst:26
#, fuzzy
msgid ""
"**Actions**: Provide details about where critical infrastructure might be "
"flooded"
msgstr ""
"**Actions**: Menyediakan rincian mengenai dimana area yang tergenang banjir "
"berada"

Proposed solution

Investigate when and how strings are marked as fuzzy
describe and document the workflow to ensure that translators and coders know how to ensure that all translations are used properly

Expected outcome

we understand the causality of translation issues such as fuzzy
documentation translations are as complete as the completed translation work that has been carried out.

Compiling the documentation should produce no warnings or errors

Problem Description

When we compile the sphinx documentation using:

scripts/post_translate.sh

there are many errors, warnings and other 'noise' produced on the console. This makes it

very difficult to see where issues may have arisen when new documentation sources are added or documentation is updated, and,
likely that there are potential inconsistencies and errors in the documentation we produce.

Desired outcome

Build should complete with minimal feedback on the terminal and the user should only need to pay attention to it if new issues have been introduced into the documentation tree.

Symptoms

During building of docs, a lot of stderr noise is generated like this:

/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/preparing_a_release.rst:301: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/profiling.rst:21: WARNING: Literal block ends without a blank line; unexpected unindent.
/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/profiling.rst:24: WARNING: Literal block ends without a blank line; unexpected unindent.
/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/realtime.rst:220: WARNING: Literal block expected; none found.
/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/realtime.rst:371: WARNING: Inline strong start-string without end-string.
/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/realtime.rst:440: ERROR: Unexpected indentation.
/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/realtime.rst:441: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/writing_impact_functions.rst:55: ERROR: Unexpected indentation.
/home/timlinux/dev/python/inasafe-dev/docs/source/developer-docs/writing_impact_functions.rst:98: ERROR: Unexpected indentation.
/home/timlinux/dev/python/inasafe-dev/docs/source/user-docs/impact_functions.rst:70: WARNING: Bullet list ends without a blank line; unexpected unindent.
/home/timlinux/dev/python/inasafe-dev/docs/source/user-docs/impact_functions.rst:72: ERROR: Unexpected indentation.

and on completion of the build one sees warnings listed like this:

copying TeX support files... done
build succeeded, 59 warnings.

Proposed Solution

We should fix all errors and warnings currently exhibited in the documentation.
We should adopt a 'zero errors, zero warnings' policy for all documentation builds so that we will immediately be aware of any problems that may arise.
We should provide helpful feefback if errors do occur and exit the build process with an error.

Budget numbers in road-map?

Problem

There are a lot of detailed budget amounts written into
road-map/rolled-over-2012.rst. Do we really want to have that inside the public documentation?

Solution

Delete the passages containing detailed numbers.

Documentation needs a complete review.

Problem

Attrition is a natural occurrence in documentation. We need to prevent this by regularly checking that it is current and correct.

Proposed solution

Manually review each and every page of documentation for the following elements:

consistent writing style
consistent use of markup
logical consistency (e.g. each section following on logically from the previous)
valid and up to date intra and extra document links
clear and up to date screenshots
current and correct information relating the use and functionality of InaSAFE
all sections having an appropriate anchor so that we can 'hook' into that context from the program code to display localised help for a given context.

Expected outcome

When a user uses the documentation he should encounter clear, logical and consistent text that helps him / her achieve the tasks they are trying to carry out.

Search button needs improvement

Problem

The search bar button on the web site looks inconsistent with the rest of the site.

Proposed solution

Add these classes to the button using a little jquery in the index.html template:

class="btn btn-warning btn-small"

It will look like this after the style is applied:

Expected Outcome

The search bar fits in well with the rest of the site

Clarify AIFDR-AUSAID abbreviations

Problem

Going through the Documentation we have a lot of occurances of

Australia-Indonesia Facility for Disaster Reduction (AIFDR-AUSAID)
AIFDR-AUSAID (Australia-Indonesia Facility for Disaster Reduction)
just AIFDR-AUSAID
just Australia-Indonesia Facility for Disaster Reduction

As I was just told to replace every occurance of AIFDR to AIFDR-AusAID it looks a bit weird now to not have the full explanation of the AIFDR-AusAID abbreviation.

Proposed Solution

To have a consistent look and feel we should choose only one of them.
My suggestion would be just to use the abbreviation AIFDR-AusAID everywhere and make

some list of used abbreviations at the end of the documentation where it is only written once or
link every occurance of AIFDR-AusAID to a Webpage like http://www.ausaid.gov.au/countries/eastasia/indonesia/Pages/humanitarian-init1.aspx

Expected Outcome

There is the same AIFDR-AusAID on every page (probably linked to the Homepage of AIFDR-AUSAID) that does not look to the reader as there are different organisations.

And as I have seen just now in the Web (googled for it) AUSAID is rather spelled AusAID

Kristy could you please tell what I should do and clarify AUSAID or AusAID?

We need to make it easy for casual users to join us on IRC

Problem

Sometimes users need interactive help - or to chat directly with a developer. Currently the preferred way to do this is on IRC but we need to make it easy for them to use it.

Proposed solution

I have looked at a number of web chat solutions:

hipchat (great but proprietary)
kandan (foss but doesnt work so well)
various other AJAX clients

While I am not completely happy with it, I think we should stick with IRC until we find something better. To make things easier for our users we should embed the client directly into out site as they have done here:

http://podcast.ubuntu-uk.org/live/

In order to do this in the sphinx context, we should make a new page template (similar to index.html) and add it to the conf.py. This page should have the web chat client embedded in it as per the above example. It could be accessed via a 'Chat live!' menu option at the top of the screen.

The page should include instructions explaining to users that other chat members are not always watching the chat directly and that they should type their questions and stick around until someone sees they are there.

Expected outcome

Our users should be able to get into contact with developers and other users directly, interactively and easily.

Help for InaSAFE user

I just wondering as InaSAFE new-user. I open the documentation in inasafe.org. But I couldn't find where I can get help using InaSAFE. The most related is this page: http://inasafe.org/user-docs/getting_involved.html

But, the title is Getting Involved, and as new user, I think it's not so common for getting help.

Another problems:
The ways to contact inasafe team is a little bit hard for new users.

Visit our web site! --> If the users read that page, it means that the users have already visit the web site.
Join our mailing list! --> We can add the direct link for the group : https://groups.google.com/forum/?fromgroups#!forum/inasafe-users. It will be more helpful for the user than subscribing the miling list.
Use our issue tracker! --> Good for github-user. But I don't think most user have github account or never heard github before. So, they couldn't add new issue.
Chat live to developers on IRC! --> Great for IRC-user. But, I don't people use IRC in common.
Submit your code! --> obviously, not for new users

So, I think we need to add a page for getting help for new users. And if possible, easier way for new user to get help.

What do you think @vanpuk @timlinux @mach0 ?

We need more images for the new web site rotating banner

Problem

The new web site will go live with 1.2. It would be good to add more pictures and captions for the front page rotating banner.

Proposed solution

Crop this image for the front page:

http://www.flickr.com/photos/gem_foundation/sets/72157631998166973/show/

and perhaps some group pics from that gallery.

Ask @vanpuk and @ismailsunni if they have any additional images from training courses and perhaps relevant disaster contingency planning related images that they can make available.
Add the accumulated images into the docs repo front page template.

Expected outcome

Visitors to the front page of the site will be greeted with a series of interesting and topical images which portray both the people involved in the project and the scenarios that InaSAFE is designed to create contingency plans for.

Bahasa user docs are not showing

Problem

Currently no Bahasa translations are appearing in the http://inasafe.linfiniti.com test site except for the front / static page(s).

Proposed solution

Check that transifex resources are being retrieved properly
Manually check .po files
Manually run post translate (locally) and check outputs

Expected outcome

As far as available, the site should be displayed in Bahasa

We need to resolve rendering issues with IE 8 and 9

Problem

The site does not render well on IE 7, 8, 9.

IE 7

IE 8

IE 9

I tested using http://www.browserstack.com/screenshots/ (we should include this as a standard part of our testing process).

Proposed solution

Search around online - the issues obviously relate to our using bootstrap.
Other pages should be checked too, not just the front page

Expected outcome

Users stuck (poor souls) using IE < 10 should get a good experience when visiting our site otherwise all the work we have put into it will be wasted.

Note

I am going to mark this as a blocker for the launch of the new site.

CC

@vanpuk

Empty Documents that should include something

Description

According to the document on lucidchart (https://www.lucidchart.com/documents/edit/4fe7-01ec-51b9760c-b9ff-46d70a004538) I have cleaned and structured the Documentation in user-docs and moved some things into "general" (and also created some new Documents as in lucidchart)

Problem

Some of this new files are (more or less) still empty (I tried to put at least some useful information there) and I currently have no information about howto fill them. Being empty does not look good.

These Files are:
in the general folder

news.rst
activities.rst (anyone has dates for meetings?)
screenshots.rst (someone has nice up to date screenshots?)
sponsors.rst (working on that.. think we have to bring the logos in)
scientific-references (what about the articles we already had there - or does that more fit into news?

Proposed Solution

Fill that files with Information

@wonderchook

We need to include a governance page listing the PSC and TWG members

Problem

We don't have much information on how the project governance works and who the role players are. @mach0 was working on an organogram for the project and it should be augmented with PSC and TWG members as well as perhaps having a separate governance page describing how the project is governed.

Proposed solution

@mach0 to put the scaffolding of pages in place for governance section (including ensuring it lands up in transifex etc)
@mach0 to add PSC and TWG to the organagram
@vanpuk to supply details needed (or simply edit the docs Werner creates above)

Expected outcome

It should be clear how the governance of the project works, who signs off on releases etc.

restructuring the whole documentation

Problem

The current documentation is now compiling without any errors but going through the whole documentation you can see that there is a lot of redundant information and probably miss located documentation which should be moved and collected under an other topic.

Problem

The search box in the navbar runs right up against the edge of the div and it doesn't look so nice.

Proposed solution

Add some padding to the nav div:

padding-right: 10px;

In addition I suggest to add the following style rule to round the corners of the nav bar a little:

border-radius: 4px;

These rules should be added in the inasafe.css overrides so that we can update bootstrap in the future easily.

Expected outcome

The navbar should look gorgeous!

Adresses for the [email protected] group

Getting info over from Issue #22

Responsibilities depending on the mail topic/content

Indonesian specific questions - AIFDR or BNPB representative
Country specific questions (other than Indonesia) - World Bank-GFDRR representative
Technical questions - Linifiniti or Ariel
Documentation - Linfiniti
Training documentation - AIFDR to direct to HOT

Persons to be added to [email protected]

BNPB - I suggest Pak Agus - https://github.com/aw3126
WB-GFDRR - Abby Bacca - [email protected]
WB-GFDRR - Liana Razafindrazay - [email protected]
WB-GFDRR - Ariel Nunez
AIFDR - Kristy Van Putten - https://github.com/vanpuk
Linfinit - timlinux
Linfiniti - mach0

Can I just add the missing persons? Are they already informed? Do they agree? Because I don't want to put someone on a list without the permission to do so!

Indonesian translations need to be approved

Problem

Currently the Indonesian translation is at 78% but very few of the translations actually show because most are not approved. When translations are not approved, they do not make their way back into the generated web site / docs.

Proposed solution

Have a native Indonesian speaker review all the existing docs and approve them.
Maintain the translation approvals on an ongoing basis.
Temporarily assign Dika to this task since Emir is away at the moment

Expected outcome

Documentation and web site should show native Bahasa Indonesia language text in every place where it has been translated.

CC

@vanpuk
@mach0
@wonderchook
@emirhartato

split off user-doc

Problem

To refer to and ship the user documentation separately with the InaSAFE plugin we need to compile the user-doc separately too.
Therefore several tasks have to be done:

Steps to do:

Documentation reorganisation to also have the pictures inside user-docs
Review everything and reorganise the functional docs (user-docs folder)
Create a script to build only the user-docs folder and package it to ship with the plugin
Adjust layout to only display the necessary information as a help page

@timlinux
@vanpuk

We need a link to the generated pdf's on the InaSAFE documentation web site

Problem

Currently in the 'new' web site (prototype visible at http://inasafe.linfinit.com) there is no way to easily get the generated pdf's built by Jenkins.

Proposed solution

Include prominent links on the front page
Use a url scheme that is easy to remember e.g. http://inasafe.org/pdfs for users wanting to browse current and old versions of the docs

Expected outcome

A user looking for the PDF documentation can easily find it on the new web site

Searchbox in Topmenu

Problem

Putting the searchbox in the Topmenu to have it central available renders it nonfunctional in subdirectories because search.html should only be called from the document root.
And there is the "Hide Search Matches" function coming from doctools.js which cannot be disabled.

Explanation

Do further investigation if this could be done with plain sphinx.
The sphinx default is setting search.html to ./search.html which would only work if you are in the root directory but not in any subdirectory.

Current solution

Basically the current solution renders pathto(master_doc) to ../contents.html but for contents.html itself it renders it to # which would make the path unuseable for contents.html.
Changing action="search.html" to action="{{ pathto(master_doc) }}/../search.html" to make it work in subdirectories and also change the path to search.html in contents.html (which is the only one causing problems because it IS the root document for Documentation with the post_translate.sh script
rpl '#/../search.html' 'search.html' ./output/html/${LOCALE}/contents.html

Probably this is the only way to solve it but for now I'll leave it that way as it works to have a deeper look into sphinx later.

searchbox
doctools.js

writing API docs is outdated

Problem

According to issue #4 the "writing API Documentation" is outdated

Proposed solution

Please rework the file
/docs/source/developer-docs/writing_api_documentation.rst
according to the current workflow

Expected outcome

A brief guideline for developers howto make their modules/functions automatically visible in the documentation

We need a high level systems architecture document

Problem

We dont really have any documentation in the developer docs that describes InaSAFE at a high level such that new developers can quickly get to grips with the project architecture.

Proposed solution

Add a new section to the start of developer docs that describes the InaSAFE architecture. The following diagram (or this and others) could be used to allow the reader to visualise the written description.

Expected Outcome

New developers and project members can quickly gain an understanding of the hight level components of the system before digging into specifics.

We need to include the 1.2 release announcement on the web site front page.

Problem

InaSAFE 1.2 is nearly ready - we need to include it on the front page as an announcement.

Things needed

You tube clip added to the video wall on front page http://www.youtube.com/watch?v=Ad-NhWVxWNU
Finalise release changelog and convert to RST and incorporate into docs (maybe in a new 'releases' folder)
Translators to translate changelog and front page updates (note latter has to be done manually on index-id.html)
Werner to deploy these updates to site

Expected outcome

Visitors to the web site should see a clear and obvious announcement about the new release.

inasafe / inasafe-doc Goto Github PK

inasafe-doc's Introduction

InaSAFE

Quick Installation Guide

Participation

System Requirements

Running tests

History

Disclaimer

License

Disclaimer of Warranty (GPLv3)

Limitation of Liability (GPLv3)

inasafe-doc's People

Contributors

Stargazers

Watchers

Forkers

inasafe-doc's Issues

Problem

Demo projects

Problem

Proposed solution

Expected outcome

Problem

Proposed solution

Expected outcome

Problem

Proposed Solution

Outcome

Problem

Proposed solution

Expected outcome

CC

Problem

Solution

Problem

Proposed solution

Expected outcome

CC

Problem

Proposed solution

Expected outcome

Problem

Proposed solution

Expected outcome

Problem

Problem

Proposed solution

Expected outcome

Problem

Proposed solution

Expected outcome

Problem

Currently

Change

Problem:

Solution

Enhancing

Problem

Proposed solution

Expected outcome

CC

Problem

Proposed solution

Expected outcome

Problem

Proposed solution

See also

Expected Outcome

Problem

Solution

Problem

Proposed solution

Expected outcomes

CC

Problem

Proposed solution

Expected outcome

Problem

Proposed solution