[Freeciv-Dev] Re: freeciv documentation project

[Brandon Craig Rhodes <brandon@xxxxxxxxxxxxxx>]

Mike Kaufman <kaufman@xxxxxxxxxxxxxxxxxxxxxx> writes:

> Brandon Rhodes <brandon@xxxxxxxxxxxxxx> has volunteered to do the
> editing work for the manuals (user, client, server).

And indeed the Game Manual has now been edited and rewritten.
Everyone is welcome to review the first draft of my effort at

        http://ten22.rhodesmill.org/civman/game.html

and are also welcome to comment on the work, provided a few caveats
are kept in mind:

 o  Comments and corrections should probably be addressed to me alone,
    rather than the whole development list, unless you think something
    important enough to warrant general debate.

 o  The text is largely complete, so mention anything that seems to
    have been overlooked; FreeCiv has many rules and some may have
    been missed.

 o  The data in the tables are generated automatically from FreeCiv
    ruleset files.  I hope to soon package the code that generates
    these tables so that ruleset developers can easily compile
    "Quick Reference" pages showing their own terrain and units.

 o  Because much of the text of this manual is based on the old one,
    information may be out of date with the current version of
    FreeCiv; though I will be perusing NEWS and CHANGELOG files over
    the coming days, I welcome any discrepancies you can bring to my
    attention.

 o  The development of cross referencing and general navigation are
    still ongoing, so please mention any problems you have finding
    material; a Table of Contents will probably appear soon on the
    front ("Overview") page, but I am too tired to write one tonight.

 o  I hope to add additional images and diagrams in the coming weeks -
    if you see any places where a visual will help comprehension,
    mention them to me.

 o  Complaints about the appearance will do me little good unless I
    know how the manual actually appears on your browser on your
    platform.  Please send such comments to me privately, along with a
    screenshot showing the page in question through the eyes of your
    browser (thus we avoid clogging the mailing list with enormous
    screenshots).

 o  The game images are generated using some scripts that I wrote, so
    other tilesets should be easy to plug in; we could conceivably
    provide alternate manuals which each used a different tileset.
    For this first draft I am using trident since I think beginners
    will enjoy a clean, diagrammatic tileset when reading the manual.
    (Trident is honestly the only tileset my eyes can parse - in the
    other ones land and units and decorations all become a muddy
    jumble for me that takes work for me to parse.  Tilesets that I
    have to pay attention to to visually parse take attention away
    from the game.)

> This means that, though perhaps preferable, you don't need to submit
> work in html. So please, especially for the client manual, we need
> writers.

My rewrite of the Game Manual was spurred by the fact that I use the
manual myself for reference during the game, and wanted to implement
several improvements that have make it much easier for me to read (we
now get to see whether it became clearer for anyone else).  But while
I plan to update the format of the Client and Server manuals to match
the appearance of the Game Manual, I have neither the time nor desire
to do much actual rewriting, and hope that others will do that work
instead.  If you want to contribute, just throw plain text and maybe
some .jpgs at me and I can do the footwork of formatting them and
getting them into the appropriate manual.

Time for bed. :-)

-- 
Brandon Craig Rhodes   brandon@xxxxxxxxxxxxxx   http://rhodesmill.org/brandon