[mapguide-internals] RE: Documenting

Wed Apr 7 19:42:15 EDT 2010

It makes the documentation much easier to access via search engines

for example, the updated error about can't connecting shows this
message via the mapagent tests

Problem:\nCannot establish connection to the MapGuide
Server.\n\nPossible Causes:\n-Your session has been idle for too
long;\n-MapGuide Server is no longer responding;\n-Internet connection
problems.\n\nSolution:\nRestart your application / session, restart
the MapGuide Server service, or contact with the server administrator.
Problem:\nCannot establish connection to the MapGuide
Server.\n\nPossible Causes:\n-Your session has been idle for too
long;\n-MapGuide Server is no longer responding;\n-Internet connection
problems.\n\nSolution:\nRestart your application / session, restart
the MapGuide Server service, or contact with the server administrator.

Ignoring the \n issue, this is a rather verbose error message

If there was a error code MG001, the user could then simply google it and
find (any) related documentation, mailing list posts or blog entries
which relate
to this error.

Error: MG001 Cannot establish connection to the MapGuide Server

Is much clearer and provides the user with a simple action path if
they don't know
what has happened. search for MG001 which would then bring the user to
a trouble shooting page on the wiki.

z

On 8 April 2010 09:34, Tom Fukushima <tom.fukushima at autodesk.com> wrote:
> Zac, I'm not sure how this is related to documentation.  Sounds like you want changes to error messages or logging that was specified in an RFC 49, or the work on detailed exceptions in RFC 79; if so, that's not covered by this "Documenting" task.
>
> Tom
>
>
> -----Original Message-----
> From: mapguide-internals-bounces at lists.osgeo.org [mailto:mapguide-internals-bounces at lists.osgeo.org] On Behalf Of Zac Spitzer
> Sent: Wednesday, April 07, 2010 5:21 PM
> To: MapGuide Internals Mail List
> Subject: Re: [mapguide-internals] RE: Documenting
>
> Can we consider introducing error codes which make diagnosing problems
> a lot easier than searching for fairly generic error messages?
>
> It makes working with Oracle very easy to research and solve problems
>
> z
>
> On 7 April 2010 22:04, Martin Morrison <martin.morrison at edsi.com> wrote:
>> It was disorganized and inaccurate enough I didn't bother trying to continue.  There was a big disconnect between what I was reading on the list about building/compiling vs the documentation.
>>
>> -----Original Message-----
>> From: mapguide-internals-bounces at lists.osgeo.org [mailto:mapguide-internals-bounces at lists.osgeo.org] On Behalf Of Tom Fukushima
>> Sent: Tuesday, April 06, 2010 7:19 PM
>> To: MapGuide Internals Mail List
>> Subject: [mapguide-internals] RE: Documenting
>>
>> Thanks for your input Martin and Walt.  As Jason says there is some documentation for this already but when I look for it, it seems disorganized and out of date.  Other than that do you have see any other problems with the existing documentation on building and configuring?  If not I will see if we can put some time into organizing it and making it up to date!
>>
>> Thanks
>> Tom
>>
>> -----Original Message-----
>> From: mapguide-internals-bounces at lists.osgeo.org [mailto:mapguide-internals-bounces at lists.osgeo.org] On Behalf Of Walt Welton-Lair
>> Sent: Monday, April 05, 2010 11:30 AM
>> To: MapGuide Internals Mail List
>> Subject: [mapguide-internals] RE: Documenting
>>
>> I agree with Martin.
>>
>> -----Original Message-----
>> From: mapguide-internals-bounces at lists.osgeo.org [mailto:mapguide-internals-bounces at lists.osgeo.org] On Behalf Of Martin Morrison
>> Sent: Monday, April 05, 2010 1:15 PM
>> To: MapGuide Internals Mail List
>> Subject: [mapguide-internals] RE: Documenting
>>
>> Building.  You have to build it before you can configure it...
>>
>> Configure. You have to configure it before you can debug it...
>>
>> I'm partial to Windows/Apache, but both should be done...Windows first <G>.
>>
>>
>>
>>
>> -----Original Message-----
>> From: mapguide-internals-bounces at lists.osgeo.org [mailto:mapguide-internals-bounces at lists.osgeo.org] On Behalf Of Tom Fukushima
>> Sent: Monday, April 05, 2010 1:11 PM
>> To: MapGuide Internals Mail List
>> Subject: [mapguide-internals] RE: Documenting
>>
>> (Resending with hopefully better formatting than last time)
>>
>> Hi Developers,
>>
>> We have some money that we would like to put toward documentation (http://producingoss.com/en/producingoss.html#documentation) in order to make the barrier for new developers lower; if you could only pick one or two from the following which would you pick?
>>
>> 1 Web Tier Component Architecture
>>
>> 2 Building MapGuide Server and Web Extensions on Linux
>>
>> 3 Building MapGuide Server and Web Extensions on Windows
>>
>> 4 Configure Web Extensions on Apache/Linux
>>
>> 5 Configure Web Extensions on Windows/IIS
>>
>> 6 Server and Web Tier Debugging HOWTO (Windows and Linux)
>>
>> 7 Running and maintaining Server and Web Tier Unit Tests
>>
>> 8 Branches for FDO and MapGuide
>>
>> 9 Document Render Service HTTP APIs
>>
>> 10 Other: please specify
>>
>> This work is already in progress so please respond as soon as you can.
>>
>> Thanks
>> Tom
>> _______________________________________________
>> mapguide-internals mailing list
>> mapguide-internals at lists.osgeo.org
>> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
>>
>> _______________________________________________
>> mapguide-internals mailing list
>> mapguide-internals at lists.osgeo.org
>> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
>> _______________________________________________
>> mapguide-internals mailing list
>> mapguide-internals at lists.osgeo.org
>> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
>> _______________________________________________
>> mapguide-internals mailing list
>> mapguide-internals at lists.osgeo.org
>> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
>>
>> _______________________________________________
>> mapguide-internals mailing list
>> mapguide-internals at lists.osgeo.org
>> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
>>
>
>
>
> --
> Zac Spitzer
> Solution Architect / Director
> Ennoble Consultancy Australia
> http://www.ennoble.com.au
> http://zacster.blogspot.com
> +61 405 847 168
> _______________________________________________
> mapguide-internals mailing list
> mapguide-internals at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
> _______________________________________________
> mapguide-internals mailing list
> mapguide-internals at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/mapguide-internals
>

-- 
Zac Spitzer
Solution Architect / Director
Ennoble Consultancy Australia
http://www.ennoble.com.au
http://zacster.blogspot.com
+61 405 847 168