+1
On Tue, 15 Mar 2016 07:28:36 +1100, Cameron Shorter wrote:
Hi Massimo,
I also agree that a review process is in order. I'd actually extend to
suggest that a development process should be described as well, and that
we should align with existing OSGeo-Live documentation processes.
Ie, we should be able to find Notebook processes linked from here:
https://wiki.osgeo.org/wiki/Live_GIS_Disc#Documentation
I also think that we should describe the processes in the OSGeo-Live
wiki (which uses media wiki) rather than a git wiki. This is to ensure
consistency with the rest of OSGeo-Live. Although I'm open to being
convinced otherwise if there are strong advantages to using a git wiki.
I'd suggest following a similar style to the Quickstart guide:
https://wiki.osgeo.org/wiki/Live_GIS_Add_Project#Application_Quick_Start
For example, create a template Notebook, with comments, that someone
else can follow to create a new Quickstart.
I see our weak point from an OSGeo-Live project's point of view is
sourcing a person or people willing to provide detailed review of the
Notebooks.
In particular, it is a significant time sink reviewing documentation to
ensure it has well formed, concise English, at the standard of a
technical text book. (This is the standard we have been targeting so
far, and I believe Notebooks should also be required to meet this standard).
I'd guess that about 60% of time of creating a good notebook would be in
writing code, 40% in describing it.
Massimo, for context, your docs are quite good, but I'd estimate that
they would be ~ 10% to 20% of your effort would be required to review
the docs to our current standards. Reviewing the English in your
Quickstart took me 3 to 4 hours, and that didn't include running any of
the steps.
Sourcing someone with good English writing skills to write Notebooks
will help the review process a lot.
Cheers, Cameron
On 15/03/2016 5:08 am, Angelos Tzotsos wrote:
Hi Massimo,
I agree that we need a review process for all notebooks (not just GSoC).
+1
Angelos
On 03/14/2016 01:11 AM, massimo di stefano wrote:
From the discussion we had so far it is clear to me we need a
*official revision procedure* to have the work done for the GSoC
integrated into the live.
I agreed in “hiding” the jupyter notebook, and so the GSoC work,
from this release of the Live,
in favor of a transparent public commitment to review the efforts done.
IMHO the spreadsheet approach we use for project review doesn’t
apply very well in this context.
To facilitate keeping track of the review and facilitate potential
new contributors,
I propose to open a motion in accepting the use of github
checklist+issue tracker to keep track of the review process.
I started this page, which should help in making this possible:
https://github.com/epifanio/OSGeoLive-Notebooks/wiki/Notebook-review > >
We can improve it making it more clear, but should give you the idea.
This motion is to validate the work done during GSoC, which is:
“Development of educational material in the form of interactive notebooks”
and to help the coordination between potential contributors for this
specific topic.
Here it is my +1
Cheers,
Massimo.
--
Cameron Shorter,
Software and Data Solutions Manager
LISAsoft
Suite 112, Jones Bay Wharf,
26 - 32 Pirrama Rd, Pyrmont NSW 2009
P +61 2 9009 5000, W www.lisasoft.com, F +61 2 9009 5099
_______________________________________________
Live-demo mailing list
Live-demo@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/live-demo
http://live.osgeo.org
http://wiki.osgeo.org/wiki/Live_GIS_Disc
--
Brian M Hamlin
OSGeo California Chapter
blog.light42.com
_______________________________________________
Live-demo mailing list
Live-demo@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/live-demo
http://live.osgeo.org
http://wiki.osgeo.org/wiki/Live_GIS_Disc
