[Live-demo] Notebook-review

[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 
>> <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,  F +61 2 9009 5099