Documentation

[StefanP.MUC]

I think, up until now we don't have a clear roadmap that includes every aspect on how to document everything (code, scripts, user manual, entry points for new coders/artists).

Code
We have a central and up to date Doxyfile in "documentation/" Most of the new code is already doxygen compatible documented (\brief, \param, \return, \file...). Old code is still lacking documentation, but this should be done on the fly while refactoring it.
We should regulary upload the doxygen generated documentation to our sf page and link it from the wiki.

Scripts
For the first script (console.as) I used doxygen documentation for a start, but I'm not sure if this works (Doxygen has no AS parser). We will still have to figure what's the best way here.
In the end, we should upload an autogenerated documentation here, too.

User manual
The gameplay should be documented. This includes console commands. The specifics need to be worked out.

Repositories
We already have a README file on git root, it explaines the different folders and provides some links to the wiki and a quick compile guide. I think this is enough.
Something like this should happen on svn, too (along with mabe some cleaning up, unused/ and mediaSource/ could need some cleaning).

Any further input and opinions are welcome. I'll update this roadmap accordingly.

[oln]

We also need documentation for the creature definition files, (once the definition is finalised), and the map format if it doesn't exist. (Though we could end up altering it to some extent.)

For the code we should also have some documentation describing the current thread model. (There is one I posted on the forums.)

We should look through the documentation for model/sound formats etc. , and see if it's up to date. We should have a simple guide for people wanting to contribute media.

[svenskmand]

Sounds good. This stuff should also be available on the webpage. What did we agree on here, was it wordpress?

The manual could be made in LaTeX.

[oln]

Sounds good. This stuff should also be available on the webpage. What did we agree on here, was it wordpress?

The dev related stuff should be on the wiki.
I think we agreed on making a simple worpress page containing parts that are of interest to players, and keep the wiki for dev things?

[StefanP.MUC]

The website don't has any agreement, I think. Once in a while some new people are offering their website making skills but then aren't coming back.

I think the latest state was to stay with the MediaWiki software and create a better skin (not only colors, but also a nice horizontal header with a good navigation) and write a handful of entry point pages (development, downloading, documentation) with links to indepth information.

Not sure about the user manual in Latex... This is hard to maintain. If we ship a manual with each release, then I'd say we use a plain HTML manual. If we don't ship a manual, then we'd add a link to the user manual on our website.

[oln]

Yeah, we were planning to have a news thing by using RSS from the forums as well, but we are still waiting for the forums to be updated to make that possible.

It's easier and more flexible to write a user manual in LaTeX rather than plain HTML if it's to be shipped with the game (If you know LaTeX that is, otherwise it's worth learning.) You can generate HTML with latex as well.

[StefanP.MUC]

Yes, I know Latex, already wrote several scripts and thesis for university with it.
Seems I'm outnumbered, then we should use Latex, I think.

[Knitter]

If you don't want to use Latex you could try something like Asciidoc, http://www.methods.co.nz/asciidoc/

Being simple text it's easy to write and maintain, and can go pretty well with source control software, it also allows you to export to various formats, from simple HTML to PDF or even some other format.

I use it often to write documentation, books and articles and it's pretty easy and powerful.

[StefanP.MUC]

Another possibility would be to write the user manual in the wiki and use MediaWiki's html or pdf export features to generate a stand-alone version of it.

[svenskmand]

I would prefer LaTeX, it makes nicely formated/layouted documents, and as oln said it supports html output too.

[Knitter]

That's why I suggested AsciiDoc, you can transform the text documents to various formats, like HTML and PDF with proper control for the layout and if you need you can even convert to Latex. Most of the times I feel asciidoc to be a better option than Latex as it's easier to use and offers the same results allowing me to write in a simple text editor without the cryptic Latex markup

[svenskmand]

I also prefer LaTeX since both stefan, oln and I knows it. I write LaTeX on a daily basis.

Cryptic makeup?

[Knitter]

Cryptic makeup?

Begin/end, brackets and font sizes in the document, dashes in section names, all the section names... I spent more time looking at documentation to see how something was written then writing my texts. In the end I needed to look for something that I could learn to use in 10 minutes and that was powerful enough for what I wanted to create, latex was a no go . Maybe I could have given it more time but I do more with Asciidoc and with a smaller learning curve and the source file is in a format that everyone can read without being bothered by tags they don't understand.

[astyanax]

Is there any article/document available describing the current development process, or a quick intro for devs?

[Skorpio]

Hi astyanax, the current process is, pick a task and do it. It would be nice, if we had a list/article where people could declare their current task. I think everything needs to be organized better and we have to communicate more. Here's a list of tasks: viewtopic.php?f=45&t=3896

I guess you can find more information on the website and the wiki (or ask Oln ): http://opendungeons.sourceforge.net/development.html