[mapserver-dev] Feedback required: plans for Downloadable Users Manual

[Jeff McKenna]

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