inasafe / inasafe-doc Goto Github PK
View Code? Open in Web Editor NEWDocumentation project for InaSAFE
Documentation project for InaSAFE
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.
It should be clear how the governance of the project works, who signs off on releases etc.
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.
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.
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.
Going through the Documentation we have a lot of occurances of
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.
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
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?
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).
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.
I am going to mark this as a blocker for the launch of the new site.
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.
I have looked at a number of web chat solutions:
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.
Our users should be able to get into contact with developers and other users directly, interactively and easily.
As the functional documentation is completely reworked and restructuring
I found
Things to cover (suggested by Trias Aditya)
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.
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.
We need a way to formalise the process large architectural changes to the code base.
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).
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.
The whole Documentation is being reworked and extended with sphinx functionality.
The Translation should keep up with the original Documentation.
Go through every rst file and translate it and rework the added sphinx functionality.
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
Attrition is a natural occurrence in documentation. We need to prevent this by regularly checking that it is current and correct.
Manually review each and every page of documentation for the following elements:
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.
We need to ensure that when QGIS 2.0 comes out it is fully translated into Bahasa Indonesia
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.
Rename the file and all references to it in:
Proposed new name: create_api_docs.py
Proposed new name: create_impact_function_docs.py
The purpose of script should be obvious from the file names.
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.
Collecting missing issues from #3
There is the Idea of having it structured like that:
See the DocumentationStructure as produced and updated it lucidchart
Adding persons here:
@timlinux
@emirhartato
@wonderchook
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.
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.
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.
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
Would you please take some time and translate that page. Everything is already prepared and in place.
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 ..
Found another file with nearly no content
I'll attach the content here to have it available::
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.
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.
A user looking for the PDF documentation can easily find it on the new web site
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
Text on the front page needs to be edited
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.
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).
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.
Currently no Bahasa translations are appearing in the http://inasafe.linfiniti.com test site except for the front / static page(s).
As far as available, the site should be displayed in Bahasa
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.
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.
New developers and project members can quickly gain an understanding of the hight level components of the system before digging into specifics.
Currently we have no idea of who and where our users are.
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.
Even when reading the docs, projective users really don't have a good idea of what InaSAFE will produce.
Note: Use the scenario data from the InaSAFE data packages it has sufficient data to test all impact functions.
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"
We need to ship with up to date translation of context help.
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.
BI Users should have a great experience when using the context help in InaSAFE.
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.
@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.
When arriving at the inasafe-doc repo, there is no obvious starting point
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
New document writers will find the help the need to get started when they arrive at https://github.com/AIFDR/inasafe-doc
Getting info over from Issue #22
Responsibilities depending on the mail topic/content
Persons to be added to [email protected]
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!
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.
According to issue #4 the "writing API Documentation" is outdated
Please rework the file
/docs/source/developer-docs/writing_api_documentation.rst
according to the current workflow
A brief guideline for developers howto make their modules/functions automatically visible in the documentation
InaSAFE 1.2 is nearly ready - we need to include it on the front page as an announcement.
Visitors to the web site should see a clear and obvious announcement about the new release.
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?
Delete the passages containing detailed numbers.
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.
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.
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:
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
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.
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.
Only relevant modules should be listed in the API docs.
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'?
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.
All documentation related to InaSAFE should be available in one comprehensive documentation set.
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.
Developer docs should not show as translatable
The search box in the navbar runs right up against the edge of the div and it doesn't look so nice.
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.
The navbar should look gorgeous!
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
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
Just have a look and tell me if it is fine that way or where I should adjust some things.
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.
Issue #3
Providing clear guidelines and regularly auditing the documentation to ensure guideline compliance will prevent the documentation from losing quality over time
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?
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.
Could you please translate that into Bahasa in the file index-en.html and commit that?
People not understanding english and visiting the Webpage can easily read that sentence and switch to Bahasa.
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)
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
Fill that files with Information
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
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.
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.
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.
The search bar button on the web site looks inconsistent with the rest of the site.
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:
The search bar fits in well with the rest of the site
The text on IRC needs to be improved
Old:
New:
Old:
Users can easily understand the text displayed on the page.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.