Wanted: Volunteers to write fool-proof documentation

[GoogleCodeExporter]

GeoToad needs some documentation beyond the man page, shedding light on its 
internal mechanisms (in particular, user profile parsing and file caching), and 
how they can be exploited the best - and where the tripwires are. Some "Dos and 
Don'ts", spiced with Real Life Examples.

I agree that program authors should document their work, but there's also the 
non-zero chance of becoming blind for the obvious... I've been contributing to 
GeoToad for almost three years, which is too long for a "naive" look (which is 
what we need IMHO). I _am_ willing to contribute a lot of my personal stuff: 
how I build input files for GCStatistic (including my own found logs); how I 
post-process my query results to merge mystery solutions; etc., stuff that has 
also grown over 3 years and just works for me.

So I'm looking for a few happy GeoToad users who would like to say Thank You in 
a slightly different way: by e.g. setting up an EtherPad to work on a short 
GeoToad Beginner's Manual. (The result may end up in the Wiki, of course.)

Any volunteers?

Original issue reported on code.google.com by Steve8x8 on 27 Sep 2013 at 1:23

[GoogleCodeExporter]

Some ideas:
1. History of GeoToad (geocrunch 2002, geotoad 2003-)
   - got to find whether the original author had written about this
2. Concepts and inherent limitations of GeoToad (file cache; store 
configuration, cookies, GUID mapping in YAML; use "printable pages" instead of 
"cache details" because of frequent redesigns)
3. Installation of GeoToad (which package to download, prerequisites, caveats, 
compatibility problems)
4. First steps with GeoToad (TUI, what it can do and what it cannot; basic 
examples)
5. Expert use of GeoToad (command line mode, use in scripts, special use-cases 
like "along a route" or "latest caches in the vicinity" etc.)
6. Additional software to use with GeoToad output (gpsbabel, geo-*, GSAK, ...)
7. Perhaps a fully-fledged setup:
   - prepare for daily geocaching work: cache lists, spoiler images, maps
   - maintain list of own finds
   - maintain own logs
   - create input for GCStatistic ...
Appendix: some useful tables like country and state IDs, attribute codes

LaTEX snippets preferred.

Original comment by Steve8x8 on 14 Nov 2013 at 1:40

• Changed state: InfoNeeded

[GoogleCodeExporter]

In the discussion below Issue 288, there's a request for a step-by-step 
walkthrough "how to use SVN trunk and patches". If someone would be willing to 
write up such instructions, please include a pointer to the "work in progress" 
page which always has the latest and greatest patches.

Original comment by Steve8x8 on 20 Nov 2013 at 1:08

[GoogleCodeExporter]

Issue 284 has been merged into this issue.

Original comment by Steve8x8 on 22 Dec 2013 at 1:05

[GoogleCodeExporter]

The SVN logs show that the first revision was committed on Apr 21, 2003. This 
means that in a little less than three months, GeoToad will celebrate its 12th 
birthday.
Some decent user manual would be a nice birthday present, I think.

I consider myself too involved in coding to write proper _user_ documentation, 
but of course I'm willing to share a couple of use cases.
Any volunteers?

Original comment by Steve8x8 on 23 Jan 2015 at 10:28

[FredFronky]

Thanks for you help with my other problem I had some time ago. I know I've been a little slow with my reply, but I was having problems with my Ruby installation, and it took me a little while to get them sorted out. Now I've worked that out, Geotoad is running beautifully. Thanks a lot.

I made up this PDF to help out a non- techie friend with setting up Geotoad, and I thought I'd share it here. Do with it what you will. Thanks again, FredF Geotoad.pdf

[steve8x8]

Thank you - if some day you decide to extend your document you'll be welcome ;) A short remark: your method clones the git repository which is work in progress. This means that there's no version string available (as that gets inserted only when a release is packaged), and there's a small risk that it's broken (I'm trying to only commit patches that have been somewhat tested). I don't complain - this will provide some testing before a release is rolled - but you should be aware of that.

[steve8x8]

Bumping to high priority: If you know of any manual or other instructions in any language I'd like to know. If you wrote something yourself - in a blog, in a magazine, whereever - that might be useful for GeoToad beginners, please share. In particular, I'm curious whether any instructions exist for how to combine GeoToad with your favourite iOS geocaching app -- I keep getting requests for that (mostly because there's no c:geo equivalent for iOS, but some apps can import GPX). Thanks.