[mapguide-trac] #1614: Updated MapGuide Developer's Guide

[MapGuide Open Source]

#1614: Updated MapGuide Developer's Guide
-----------------------------+----------------------------------------------
   Reporter:  jng            |       Owner:  jng                    
       Type:  task           |      Status:  new                    
   Priority:  medium         |   Milestone:                         
  Component:  Documentation  |     Version:                         
   Severity:  major          |    Keywords:  devguide, documentation
External_id:                 |  
-----------------------------+----------------------------------------------
Description changed by jng:

Old description:

> The original MapGuide Developer's Guide has several problems associated
> with it:
>
> 1. It used PHP in all its code samples. The problem is if you didn't know
> PHP, but knew .net or Java then the actual document does not really help.
>
> 2. The document is essentially a blob, making it unsuitable for storage
> under source control as changes cannot be tracked.
>
> 3. The document does not exist in source form (related to point #2).
> Having the document source allows us to "compile" it into multiple
> different forms (html, pdf, chm, etc)
>
> 4. The document has evidently not been updated in a while to reflect the
> addition of newer MapGuide APIs and the addition of Fusion and support in
> OpenLayers
>
> As a first phase, the content of the devguide should be placed into
> document source form (current thinking is either powerful like LaTeX or
> something simpler like sphinx (http://sphinx.pocoo.org))
>
> With the second phase being updating the existing PHP devguide samples to
> match current APIs.
>
> The third phase would be to port this updated sample to Java and .net
>
> The final phase would be to update the devguide content and associated
> samples with usage examples of newer APIs and examples involving fusion
> and OpenLayers.
>
> Once in place, the devguide content and examples should be regularly
> updated as newer MapGuide APIs are introduced.

New description:

 The original MapGuide Developer's Guide has several problems associated
 with it:

 1. It used PHP in all its code samples. The problem is if you didn't know
 PHP, but knew .net or Java then the actual document does not really help.

 2. The document is essentially a blob, making it unsuitable for storage
 under source control as changes cannot be tracked.

 3. The document does not exist in source form (related to point 2). Having
 the document source allows us to "compile" it into multiple different
 forms (html, pdf, chm, etc) and integrate it as part of the build process

 4. The document has evidently not been updated in a while to reflect the
 addition of newer MapGuide APIs and the addition of Fusion and support in
 OpenLayers

 As a first phase, the content of the devguide should be placed into
 document source form (current thinking is either powerful like LaTeX or
 something simpler like sphinx (http://sphinx.pocoo.org))

 With the second phase being updating the existing PHP devguide samples to
 match current APIs.

 The third phase would be to port this updated PHP sample to Java and .net
 while respecting the development style of the respective languages.

 The final phase would be to update the devguide content and associated
 samples with usage examples of newer APIs and examples involving fusion
 and OpenLayers.

 Once in place, the devguide content and examples should be regularly
 updated as newer MapGuide APIs are introduced.

--

-- 
Ticket URL: <http://trac.osgeo.org/mapguide/ticket/1614#comment:2>
MapGuide Open Source <http://mapguide.osgeo.org/>
MapGuide Open Source Internals