Level Design Documentation Rework


If you are interested in helping with tiles, vaults, patches or documentation, this is the place for that.

Dungeon Master

Posts: 1531

Joined: Saturday, 5th March 2011, 06:29

Post Thursday, 8th September 2011, 14:53

Level Design Documentation Rework

I've been working on a number of vaults, and hence referring a lot to the documentation (docs/develop/levels/*.txt).

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!

For this message the author mumra has received thanks: 2
dpeg, galehar
User avatar

Dungeon Master

Posts: 4031

Joined: Thursday, 16th December 2010, 20:37

Location: France

Post Thursday, 8th September 2011, 15:19

Re: Level Design Documentation Rework

The main drawbacks of having the crawl manual reference online is that we can't maintain separate versions for the main branches. If I want to fix a glitch in the 0.9 manual for the next minor release, it's complicated because the manual might have already been updated with 0.10 features.
We don't do much minor releases so this isn't a big deal. Also having the reference online means that non-devs can update it and I see it as a big advantage :lol:

For the developer's doc, we obviously don't care about maintaining separate branches, so keeping the reference online is fine with me. I think using reST for the manual is great. I doubt many players actually print it, but it's nice to be able to. However, for the developer's doc, wiki seems perfectly fine to me, maybe even better.

Well, in the end, what's important is to have docs as up-to-date as possible, so if someone decides to update them, let him uses his favourite tools so he does the better job and more power to him. Documenting all the lua stuff is a great move, many many thanks to you.
<+Grunt> You dereference an invalid pointer! Ouch! That really hurt! The game dies...

Dungeon Master

Posts: 3618

Joined: Thursday, 23rd December 2010, 12:43

Post Thursday, 8th September 2011, 16:20

Re: Level Design Documentation Rework

mumra: Many thanks for this. I wrote most of the current documentation (with the exception of the lua stuff, which I am not familiar with), and it is not an easy task. One the one hand, you have to give all the syntax, ideally with examples, on the other hand is the documentation so long that it surely scares off some players. (This is why I came up with the starting example, although I have no idea if it helps in any way.)

Having the documentation online would be a great help. Here is what I would suggest:
Crawl should come with a minimal documentation. It should give the main commands but does not bother to specify all the edge cases (e.g. it would mention ITEM, but not explain about decks, corpses and randart books). Together with some example file, this would allow players to locally experiment with vaults. In particular, this file should see changes only very rarely.
On the wiki, we would have the full documentation. Coders would need to update this when they add a new toy; everyone could help keeping the list of lua functions up to date (i.e. whenever you investigated an undocumented lua function, make your findings public on the wiki). I hope that especially the latter will be more convenient with wiki documentation (this is, as galehar notes, also the main advantage of having the manual online -- much easier for anyone to contribute).

Whether to use wiki or ReST does not matter much, unlike with the manual we're not really interested in fancy html or pdf versions. If you, mumra, would start this project, it'd be your choice :)

I think this is a very good idea, and if we follow it, I would offer to come up with the stripped down, core syntax documentation.

Dungeon Master

Posts: 1531

Joined: Saturday, 5th March 2011, 06:29

Post Thursday, 8th September 2011, 17:17

Re: Level Design Documentation Rework

I think, from both your comments and also my preference, just using the wiki will be the best and easiest option. People can still print out sections if they like. It'll also allow splitting the documentation into more digestible chunks, which might make it more approachable. The existing structure is very good - starting off with a simple example demonstrates right away that it's actually very easy to author a simple vault and see something working in the game. I can imagine the effort it must have been just figuring out how to get so much information in one place!

The main structural change I feel could be made is sectioning off all the LUA stuff, so there are basically two main halves to the documentation. Currently there's a point where LUA starts getting mixed in, before LUA has been properly explained. Then there's the Triggerables section, which is mostly LUA, then there's the main LUA Reference which finally starts to explain what's going on - and finally there are a few miscellaneous sections (O. Feature Names, P. Map Statistics, Q. Map Generation) which are nothing to do with LUA and seem tacked on at the end. I can see from this how all the LUA bits have been kind of shoehorned in at a later stage! (Somewhere there's a reference to Feature Names actually being section N... obviously any inconsistencies like that will be fixed in the process of adding proper links).

Thanks for the positive feedback! I agree having the LUA better documented will be a big advantage in particular. I kind of figure since I've spent the time working out particular functions, it'd be good to have somewhere to write up my findings and save others that time - and also save myself time in the future when I want to use that function again!

Dungeon Master

Posts: 1531

Joined: Saturday, 5th March 2011, 06:29

Post Thursday, 8th September 2011, 18:12

Re: Level Design Documentation Rework

The main documentation sections are now on the dev wiki: https://crawl.develz.org/wiki/doku.php?id=dcss:help:maps

I only briefly added formatting for main headings and some code regions that broke formatting completely. I'll continue updating and fixing things as and when I have time. I also need to establish a layout (probably with a wiki template) for the Lua function reference.

If anyone else on the forums has some spare time and wants to help, all contributions are welcomed!

Dungeon Master

Posts: 3618

Joined: Thursday, 23rd December 2010, 12:43

Post Thursday, 8th September 2011, 20:13

Re: Level Design Documentation Rework

mumra: many thanks for wikifying all the vaults documentation.

Is there agreement to only ship a core and stable documentation with the game? This way there should be no overlap (like we just had with galehar's mimic options).

Dungeon Master

Posts: 1531

Joined: Saturday, 5th March 2011, 06:29

Post Thursday, 8th September 2011, 23:50

Re: Level Design Documentation Rework

dpeg wrote:mumra: many thanks for wikifying all the vaults documentation.

Is there agreement to only ship a core and stable documentation with the game? This way there should be no overlap (like we just had with galehar's mimic options).


Sounds good to me.

Galehar, thanks for your update :)

Dungeon Master

Posts: 3618

Joined: Thursday, 23rd December 2010, 12:43

Post Friday, 9th September 2011, 07:41

Re: Level Design Documentation Rework

Will do.

I have improved the wiki style of a lua text. The one thing I cannot do at the moment is getting code blocks to work with lists.

Return to Contributions

Who is online

Users browsing this forum: No registered users and 9 guests

cron
Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group.
Designed by ST Software for PTF.