Dungeon Master
Posts: 1531
Joined: Saturday, 5th March 2011, 06:29
Level Design Documentation Rework
The documentation is extremely thorough on most topics, but I personally find the text file format a bit inconvenient to navigate. I should probably print it all out; but I already have too much paper lying around my desk, and in this world of internets and world wide webs perhaps there's a better way?
There are also sections of the docs that could use some serious improvement. The primary culprit being the LUA reference; it contains a massively incomplete list of LUA functions, and doesn't even tell you what parameters the functions accept, or even make it clear what a lot of functions do. I've found I mostly have to search existing *.des and *.lua files for examples, and sometimes just look directly at Crawl's source code to figure them out. This is how I started discovering there are huge numbers of entirely undocumented functions, most of which are potentially extremely useful. The section on LUA triggerables is also very hard to understand in places, and refers you to the *.lua file headers for further documentation; that information could perhaps be collated, and again it's not always complete.
So I was ready to go ahead and start wikifying the docs, and begin documenting LUA functions as I used them; I mentioned this to dpeg and he suggested the reST format (which is how the Crawl manual itself is stored: https://crawl.develz.org/wiki/doku.php?id=dcss:manual:rest). The advantage of this would be that text versions can automatically be generated from reST and included with Crawl releases, and a HTML version for online browsing. However he mentioned there are apparently problems with this (I don't know what they are).
I've started this thread to get some feedback both from devs and from vault designers on whether this would be a good idea, and what format would be best. Also, to find out if any vault designers are interested in helping convert the docs to an online format, as well as fleshing them out with more information and additional examples.
Advantages of online documentation in general:
- Easier for everyone to update; both and when vault designers notice things that are missing, or want to share example code, or when devs add new features
- Clickable table of contents
- Cross referencing; quite often the documentation refers to other sections - having hyperlinks would be wonderful, instead of manually searching through multiple large text files to find the information
- Referencing source files; for some bits of the docs it would be useful to reference Crawl's source code on Gitorious; e.g. lists of monsters, types of cloud, example .des files, etc. - saves having to maintain multiple sources of information
- Possibility of adding images, screenshots, etc.
- Easier on the eyes
Advantages of reST format:
- Can generate multiple versions (.txt, HTML, .pdf) from the same source
- Consistent with Crawl manual
Advantages of plain old wiki format:
- A lot of people are already familiar with wiki format
- Wiki has prototype support for syntax highlighting - would make examples much more readable (although: how complete is this? is it being worked on?)
- Prettier (although I assume the stylesheet for reST HTML output can be changed)
- Can images even be included using reST?
- Less work to set up, could start converting the docs immediately
- Does design documentation even need including with Crawl releases? Anyone designing vaults should ideally be referring to the latest information online; this might also encourage designers to update the docs regularly
Please note, I'm in no way trying to say one is better than the other - the advantages of reST are clearly huge, and I'd be happy for the docs to be in either format.
So, I'd love to hear some opinions on all of this, and hopefully we can start improving this resource for level designers!