[crossfire] Documentation / wiki

[Mark Wedel]

Nicolas Weeger (Laposte) wrote:

>> We could also do html docs. For that we could just to a slightly
>> modified subclass of the xhtml renderer that dokuwiki uses anyways (make
>> sure it doesn't do things that arn't friendly to static html docs. Make
>> sure link paths work for it.).
> 
> or PDF files, too, maybe? shouldn't be too hard i'm sure ;)

  I wonder how many people actually print out any of the crossfire docs - which 
is also a valid question regarding the existence of postcript files.

  As I thought about the docs some more, I did think that some general re-org, 
perhaps for 2.0, should perhaps be done:

1) Remove any old documentation that is no longer applicable - what is describes 
has been superseded or replaced by new features. (I'd tend to bet that there is 
some in the server distribution that falls in this category)

2) Move documentation that is aimed towards the player into the client 
directory, and ideally, integrate it as part of a help system in the client. 
Having docs about character creation in the server area doesn't make a lot of sense

3) Clean up the documentation that does exist - in many cases, different pieces 
of something are described in multiple files.

4) Clean up the naming scheme of the different files.  Looking in the doc 
directory, it is clear there is no standard on capitalization of file names, 
suffixes (some have a .doc but are not word files, etc).  And while the 
Developers directory was created a long time back, there is a lot of stuff in 
the doc directory which is clearly aimed only at developers and should be moved 
there.

5) Maybe some of the docs should only live on the web (with backup copies)?  I 
don't have a great example, but there are certainly a lot of docs that currently 
only exist on the web.

6) I really like the idea of going to HTML docs - it is pretty much univerally 
readable, yet is also simple to generated.  To me, the biggest bonus is the 
ability to hyperlink - that could help out point #3 above (link from one doc to 
another).  The other thing is that would help to actually have a table of 
contents so you might actually be able to find the relevant documents, where as 
now, grep seems to be the most likely.

  Regarding point #2 and #4, a layout that may make sense:

server:
doc/Manpages/: the man pages for the different programs

doc/Developers/: Information for actual programming aspects of the game.

doc/Admin/: (maybe a better name) - docs for the server admin about setting up 
and running the server, perhaps touches on changes to config files, etc

doc/MapMakers/: Information for making maps - files in here would also describe 
the archetype and treasure list information (since that is all related), how to 
add new archetypes of existing type (like adding a new sword - not about adding 
new archetypes that require code support).  Files here would also describe any 
special meaning for certain archetypes, etc.  It may be reasonable to this to 
instead be in the maps area, but since a map maker really needs their own server 
to test the maps, it may not be unreasonable to keep it here.

client:
doc/: Information that is useful to the player - how to create character, how to 
interact in the game world, the spell information (but that should really be 
moved into the archetypes itself where possible, but there are some broader 
concepts that don't really fit in there).  Hints on playing the game.  And as 
said, it would be nice to integrate this into a client help system within the 
client.