[Live-demo] Notebook-review

Tue Mar 15 02:34:16 PDT 2016

Cameron,

this efforts is to ensure the work done for the GSoC-2015 will receive a proper review as it didn’t get the required attention during the GSoC period. 
That’s the objective of the wiki page on the relative github repository.

It is obvious that notebooks as well as any other contribution to the live, needs guidelines and rules. 
in my previous mail I addressed some of them in the section:

contributing new notebooks to the live
https://lists.osgeo.org/pipermail/live-demo/2016-March/011010.html <https://lists.osgeo.org/pipermail/live-demo/2016-March/011010.html>

Of course the OSGeo wiki is the right place for those guidelines.

Note: 
Notebook guidelines is a separate task from the GSoC notebook review, where those guidelines are (and will) respected.

I started to add information here:

https://wiki.osgeo.org/wiki/Live_GIS_Add_Project#Notebooks <https://wiki.osgeo.org/wiki/Live_GIS_Add_Project#Notebooks>

feel free to move them on a temporary page if you prefer. We can make it public when ready.

> On Mar 14, 2016, at 9:28 PM, Cameron Shorter <cameron.shorter at gmail.com> 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 <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 <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.

we can agree in having a template system for heading and footer of each notebook, have a look at the header in the GSoC notebooks where the first cell is a markdown cell which help the user to navigate the notebook server filesystem 

(NOTE: you need to run the notebook in order to see it)

> 
> 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.

I’m sorry but in my understanding this should have been part of a mentor's responsibility during my gsoc.
I had a very good experience with the other 2 mentors who have don a great job in reviewing and addressing the technical part of my GSoC. 
I should remind you that according with pre-GSoC discussion your rule was to contribute in the non-technical aspects of the project.

> 
> 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 <https://github.com/epifanio/OSGeoLive-Notebooks/wiki/Notebook-review> <https://github.com/epifanio/OSGeoLive-Notebooks/wiki/Notebook-review <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 <http://www.lisasoft.com/>,  F +61 2 9009 5099

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/osgeolive/attachments/20160315/38412a9a/attachment.html>