Feedback required: plans for Downloadable Users Manual

classic Classic list List threaded Threaded
11 messages Options
Reply | Threaded
Open this post in threaded view
|

Feedback required: plans for Downloadable Users Manual

Jeff McKenna-2
Hello dev team,

I about to dive into some funded work to create a MapServer
'downloadable user's manual', to be in pdf format.  I am thinking of
making a glossy version of the great work already done by David Fawcett
and Perry in the New Users manual and the MapServer 5.0 Tutorial
respectively, and of course pointing to the existing howtos/references.
   Below are some topics for the table of contents, please let me know
if you think something is missing or if I should change my focus.

Table of Contents
-----------------

Introduction
Getting Started
   - Installing
   - Architecture of MapServer
Preparing Data
   - The .Map File
   - Supported Formats
   - Tips and Tricks
   - Factors Affecting Performance
Building a MapServer Application
   - Flavors
   - Example Code
Community
   - History of MapServer
   - Project Steering Committee
   - Contributing
   - Getting Help
   - Conferences/Workshops
Glossary


--
jeff


_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Perry Nacionales
Hey Jeff,

Looks good!  Will you be mentioning client software (ka-map!,
OpenLayers, GeoMoose, PMapper, etc.) and map file management software
(MapStorer, any others)? Perhaps you can mention these things as part of
Building MapServer Application--by the way, you can build your own
custom interface or you can use one of these clients.  I like what you
have otherwise.

-Perry

Jeff McKenna wrote:

> Hello dev team,
>
> I about to dive into some funded work to create a MapServer
> 'downloadable user's manual', to be in pdf format.  I am thinking of
> making a glossy version of the great work already done by David
> Fawcett and Perry in the New Users manual and the MapServer 5.0
> Tutorial respectively, and of course pointing to the existing
> howtos/references.   Below are some topics for the table of contents,
> please let me know if you think something is missing or if I should
> change my focus.
>
> Table of Contents
> -----------------
>
> Introduction
> Getting Started
>   - Installing
>   - Architecture of MapServer
> Preparing Data
>   - The .Map File
>   - Supported Formats
>   - Tips and Tricks
>   - Factors Affecting Performance
> Building a MapServer Application
>   - Flavors
>   - Example Code
> Community
>   - History of MapServer
>   - Project Steering Committee
>   - Contributing
>   - Getting Help
>   - Conferences/Workshops
> Glossary
>
>
> --
> jeff
>
>
> _______________________________________________
> mapserver-dev mailing list
> [hidden email]
> http://lists.osgeo.org/mailman/listinfo/mapserver-dev

_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Daniel Morissette
In reply to this post by Jeff McKenna-2
Hi Jeff,

I like what you propose. I think that we should see this as a work in
progress and additional sections/chapters can be added in future
revisions of the manual as needed, based on users feedback.

A few notes/suggestions:

- I think the interest of a downloadable users manual is to be
self-contained and not rely on an internet connection, or on external
docs unless absolutely required. In addition to pointing to HOWTOs and
ref docs in the text, what would you think of including copies of all
those HOWTOs and references in appendices at the end of the PDF itself?
Perhaps there could be two versions of the manual: the lite version
which relies on external refs, and the thick version which includes
copies of the external references in appendices? That would really be
two copies of the same document, with and without the appendices.

- Have you thought about the process to generate the manual? It would be
great to have an automated process, a kind of makefile or script that
pulls the relevant docs out of SVN, processes them and spits out the
updated manual from the latest docs. I am not the person to advise on
the tools to use to do this, I'm just making a suggestion that I think
might help long term maintainability.

My 0.02$

Daniel

Jeff McKenna wrote:

> Hello dev team,
>
> I about to dive into some funded work to create a MapServer
> 'downloadable user's manual', to be in pdf format.  I am thinking of
> making a glossy version of the great work already done by David Fawcett
> and Perry in the New Users manual and the MapServer 5.0 Tutorial
> respectively, and of course pointing to the existing howtos/references.
>   Below are some topics for the table of contents, please let me know if
> you think something is missing or if I should change my focus.
>
> Table of Contents
> -----------------
>
> Introduction
> Getting Started
>   - Installing
>   - Architecture of MapServer
> Preparing Data
>   - The .Map File
>   - Supported Formats
>   - Tips and Tricks
>   - Factors Affecting Performance
> Building a MapServer Application
>   - Flavors
>   - Example Code
> Community
>   - History of MapServer
>   - Project Steering Committee
>   - Contributing
>   - Getting Help
>   - Conferences/Workshops
> Glossary
>
>
> --
> jeff
>
>
_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Steve Lime
In reply to this post by Jeff McKenna-2
I like the outline. I think the emphasis should be strong in the area of configuration
of an application and data.  Those topics are mostly platform agnostic and don't change
that much, so the document would be more stable and useful for everyone. I can't see
wasting a bunch of time with installation discussion- the focus should be on "use".

We need to chat about the demo I'm supposed to work up. I'm leaning towards a host
of snippets that could be references in tutorials, how-to's and reference guides. For example,
you'd have an application that just focuses on labeling parameters, another on scale(denom)
and yet another on symbology. My guess is between msautotest, DNR test suite, Perry's
tutorial, and the OWS workshop materials there's plenty of content. Would be nice
to hook the manual to it as well. Perhaps the code examples good be drawn directly from
it.

Steve

>>> Jeff McKenna <[hidden email]> 03/24/08 3:40 PM >>>
Hello dev team,

I about to dive into some funded work to create a MapServer
'downloadable user's manual', to be in pdf format.  I am thinking of
making a glossy version of the great work already done by David Fawcett
and Perry in the New Users manual and the MapServer 5.0 Tutorial
respectively, and of course pointing to the existing howtos/references.
   Below are some topics for the table of contents, please let me know
if you think something is missing or if I should change my focus.

Table of Contents
-----------------

Introduction
Getting Started
   - Installing
   - Architecture of MapServer
Preparing Data
   - The .Map File
   - Supported Formats
   - Tips and Tricks
   - Factors Affecting Performance
Building a MapServer Application
   - Flavors
   - Example Code
Community
   - History of MapServer
   - Project Steering Committee
   - Contributing
   - Getting Help
   - Conferences/Workshops
Glossary


--
jeff


_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev

_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Stephen Woodbridge
Jeff,

When I read this I thought it was a great idea. You seem to have
captured the essentials in your outline. Along the same idea that Steve
has suggested of having samples. I think it would be great to also
include a complete production sample mapfile like Bob Basques Googlish
mapfile maybe in an annotated form or maybe you have your own mapfile
that would work. This might be as an appendix. The reason for this is
because snippets are great to explain this or that feature without
getting distracted by all the details, but they sometimes loose more
global context. Ultimately we are supposed to be teach people to be able
to build a production mapfile so having one, will set an expectation of
what they should be thinking about when creating one. I have no idea if
Bob would be interested in contributing it for this, but giving a
complex real world reference can be handy and it it was published with
line numbers then it would be easy to refer to a block of lines in your
text when discussing a concept.

So if you take all these ideas :) you will be writing the Mapserver
Encyclopedia.

-Steve W

Steve Lime wrote:

> I like the outline. I think the emphasis should be strong in the area of configuration
> of an application and data.  Those topics are mostly platform agnostic and don't change
> that much, so the document would be more stable and useful for everyone. I can't see
> wasting a bunch of time with installation discussion- the focus should be on "use".
>
> We need to chat about the demo I'm supposed to work up. I'm leaning towards a host
> of snippets that could be references in tutorials, how-to's and reference guides. For example,
> you'd have an application that just focuses on labeling parameters, another on scale(denom)
> and yet another on symbology. My guess is between msautotest, DNR test suite, Perry's
> tutorial, and the OWS workshop materials there's plenty of content. Would be nice
> to hook the manual to it as well. Perhaps the code examples good be drawn directly from
> it.
>
> Steve
>
>>>> Jeff McKenna <[hidden email]> 03/24/08 3:40 PM >>>
> Hello dev team,
>
> I about to dive into some funded work to create a MapServer
> 'downloadable user's manual', to be in pdf format.  I am thinking of
> making a glossy version of the great work already done by David Fawcett
> and Perry in the New Users manual and the MapServer 5.0 Tutorial
> respectively, and of course pointing to the existing howtos/references.
>    Below are some topics for the table of contents, please let me know
> if you think something is missing or if I should change my focus.
>
> Table of Contents
> -----------------
>
> Introduction
> Getting Started
>    - Installing
>    - Architecture of MapServer
> Preparing Data
>    - The .Map File
>    - Supported Formats
>    - Tips and Tricks
>    - Factors Affecting Performance
> Building a MapServer Application
>    - Flavors
>    - Example Code
> Community
>    - History of MapServer
>    - Project Steering Committee
>    - Contributing
>    - Getting Help
>    - Conferences/Workshops
> Glossary
>
>
> --
> jeff
>
>
> _______________________________________________
> mapserver-dev mailing list
> [hidden email]
> http://lists.osgeo.org/mailman/listinfo/mapserver-dev
>
> _______________________________________________
> mapserver-dev mailing list
> [hidden email]
> http://lists.osgeo.org/mailman/listinfo/mapserver-dev

_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Jeff McKenna-2
In reply to this post by Daniel Morissette
Hi Daniel,

Thanks for your feedback.  Comments inline:

Daniel Morissette wrote:
> Hi Jeff,
>
> I like what you propose. I think that we should see this as a work in
> progress and additional sections/chapters can be added in future
> revisions of the manual as needed, based on users feedback.

I totally agree.  It's quite a daunting task.

>
> A few notes/suggestions:
>
> - I think the interest of a downloadable users manual is to be
> self-contained and not rely on an internet connection, or on external
> docs unless absolutely required. In addition to pointing to HOWTOs and
> ref docs in the text, what would you think of including copies of all
> those HOWTOs and references in appendices at the end of the PDF itself?
> Perhaps there could be two versions of the manual: the lite version
> which relies on external refs, and the thick version which includes
> copies of the external references in appendices? That would really be
> two copies of the same document, with and without the appendices.

I have been writing it with the self-contained goal in mind.  I like
your suggestion of including key howtos and reference docs in the
appendix. I would prefer one version of the document though (it's going
to be quite large anyway).

>
> - Have you thought about the process to generate the manual? It would be
> great to have an automated process, a kind of makefile or script that
> pulls the relevant docs out of SVN, processes them and spits out the
> updated manual from the latest docs. I am not the person to advise on
> the tools to use to do this, I'm just making a suggestion that I think
> might help long term maintainability.
>

hmm. honestly i am 30 pages in.  I am willing to maintain this document,
  and I think the best way to make a usable document is to generate it
by hand (of course grabbing existing material along the way).  I hope
this method is ok with you.

My plan is to commit the 'mapserver-users-manual.odt' file into
/trunk/docs, and point to the pdf in the Downloads/Current section of
the site.  What do you think of that plan?  let me know.

Thanks for the feedback.

-jeff

_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Jeff McKenna-2
In reply to this post by Steve Lime
Steve,

Thanks for the feedback.  Comments inline:

Steve Lime wrote:
> I like the outline. I think the emphasis should be strong in the area of configuration
> of an application and data.  Those topics are mostly platform agnostic and don't change
> that much, so the document would be more stable and useful for everyone.

yeah since my skills are more in the data world it will hit data hard.

> I can't see
> wasting a bunch of time with installation discussion- the focus should be on "use".

I did include a section on OSGeo4W though (cool screengrabs of it in
action ha).

>
> We need to chat about the demo I'm supposed to work up. I'm leaning towards a host
> of snippets that could be references in tutorials, how-to's and reference guides. For example,
> you'd have an application that just focuses on labeling parameters, another on scale(denom)
> and yet another on symbology. My guess is between msautotest, DNR test suite, Perry's
> tutorial, and the OWS workshop materials there's plenty of content. Would be nice
> to hook the manual to it as well. Perhaps the code examples good be drawn directly from
> it.

Actually great plan.  I would love to point to your demo for the
application section and code examples.  Right now I'm working on other
sections of the manual and leaving the application section for last, so
that would hopefully work with your demo and schedule.

-jeff



_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Jeff McKenna-2
In reply to this post by Stephen Woodbridge
Stephen Woodbridge wrote:
> I think it would be great to also
> include a complete production sample mapfile like Bob Basques Googlish
> mapfile maybe in an annotated form or maybe you have your own mapfile
> that would work. This might be as an appendix.

That's a great idea Steve.  My mapfile example now is very small, I
agree it would be great to have a full Googlish mapfile included.  I
will contact Bob directly now to see if he is interested in contributing it.

thanks for your feedback.

-jeff

_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Jeff McKenna-2
In reply to this post by Jeff McKenna-2
Jeff McKenna wrote:
> I would prefer one version of the document though (it's going
> to be quite large anyway).
>

Daniel are right - as I am creating the Appendix now I see your point,
it would become very large.  So i like your 'lite' and 'full' versions
recommendation.

-jeff


_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Stephen Woodbridge
Jeff McKenna wrote:
> Jeff McKenna wrote:
>> I would prefer one version of the document though (it's going to be
>> quite large anyway).
>>
>
> Daniel are right - as I am creating the Appendix now I see your point,
> it would become very large.  So i like your 'lite' and 'full' versions
> recommendation.

Jeff,

An alternative to maintaining two overlapping documents, you could just
split the document into two files 1) the main body and 2) all the
Appendices. If these are also large files is might make managing the
downloads a little easy for some users on slower connections.

The downside of this is that the body might not be able to have hot
links to the Appendices, but then I'm not sure what you can and can't do
vis a vis PDF documents.

-Steve W
_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev
Reply | Threaded
Open this post in threaded view
|

Re: Feedback required: plans for Downloadable Users Manual

Daniel Morissette
In reply to this post by Jeff McKenna-2
Jeff McKenna wrote:

>
> hmm. honestly i am 30 pages in.  I am willing to maintain this document,
>  and I think the best way to make a usable document is to generate it by
> hand (of course grabbing existing material along the way).  I hope this
> method is ok with you.
>
> My plan is to commit the 'mapserver-users-manual.odt' file into
> /trunk/docs, and point to the pdf in the Downloads/Current section of
> the site.  What do you think of that plan?  let me know.
>

Well, I'm not the one maintaining the manual, but my initial idea was to
have it in a format that can be published on the web *and* converted to
a downloadable PDF format. I thought it could have been written in the
same ReStructuredText format as the rest of our docs and converted and
packaged into a downloadable PDF using some ReST tools.

The drawback of .odt files (or any word processor files) is that you
cannot easily track changes between revisions in SVN and cannot easily
merge changes if multiple people work on the same doc. It's just a
binary blob that is committed to the repository.

Just an opinion. I wonder what others think.

Daniel
--
Daniel Morissette
http://www.mapgears.com/
_______________________________________________
mapserver-dev mailing list
[hidden email]
http://lists.osgeo.org/mailman/listinfo/mapserver-dev