Re: [Live-demo] Notebook-review

2016-03-15 Thread massimo di stefano 
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 



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 


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

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

Re: [Live-demo] Notebook-review

2016-03-14 Thread Brian M Hamlin 

+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

Re: [Live-demo] Notebook-review

2016-03-14 Thread Cameron Shorter 

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

Re: [Live-demo] Notebook-review

2016-03-14 Thread Angelos Tzotsos 

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.





--
Angelos Tzotsos, PhD
OSGeo Charter Member
http://users.ntua.gr/tzotsos

___
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