[Live-demo] Notebook-review

Brian M Hamlin maplabs at light42.com
Mon Mar 14 13:34:08 PDT 2016


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:

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:
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
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
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 at lists.osgeo.org

Brian M Hamlin
OSGeo California Chapter


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/osgeolive/attachments/20160314/3e951667/attachment.html>

More information about the Osgeolive mailing list