[Geoprisma-dev] GeoPrisma General doc structure, proposition

[Stephen Woodbridge]

Alexandre Dube wrote:
> Yves Moisan wrote:
>>
>> A bit too big a patch for me to comment on.  There are a few typos so I
>> guess at this point just commit and I'll review.  The overall structure
>> looks ok.  Particular comments :
>>
>> - IN docs/source/introduction/index.rst :
>>   - you should  mention the datastore in between the service and
>> resource (you talk about datastores in the tutorials, so introduce it
>> here)
>>   
> 
> Got it.
> 
>> - IN docs/source/tutorials/install-strategy.rst (why
>> "install-strategy.rst" and not just "install.rst" ?)
>>
>>   
> 
> Yeah...  To me, it looks more like "my way" of installing GP, like "one 
> possibility", but we could have one recipe and edit it as the days go 
> by, adding new tips and tricks on the way...  I'll change the name to 
> install.rst
> 
>>   - I wonder if the "how to prepare your Resources" is necessary; if you
>> do put it, maybe it would be interesting to draw further parallels with
>> a layer in a mapfile or a featureserver.cfg file
>>   
> 
> Again, this portion is useful only for someone without any knowledge of 
> GeoPrisma and who doesn't know what to do at all...  I'll add pointers 
> to external doc (MapServer, TileCache, FeatureServer, etc.)

I think this is the definition of all users that are starting as newbies 
to GeoPrisma. I think the pointers for details would be ok, but walking 
a user through 1-2 layer examples would probably be useful to get the 
concept of how things are linked.

>>   - in the "Fill the requirements" section, mention there's an index.php
>> in the bundles that checks for requirements
>>   
> 
> Got it.
> 
>> That's a good start.  I think the basic architecture blocks are there.
>> A next whirl at docs could be more use case oriented.  One idea would be
>> to document samples, highlighting some peculiar options/settings that
>> cover the use case.  An example : I want to be able to tick all layers
>> off (alloverlay
>>
>>   
> 
> Absolutely.  That's one of the best way to learn : with samples 
> (examples).  I'll document mine first, add some more samples (really 
> common, like with only a map) and document them as well.

Yes samples and examples are the best. OpenLayers gets a lot of mileage 
out of their example library.

I'll have more thoughts this week once I have had time to work with 
GeoPrisma some more.

-Steve