Do we need documentation at this stage if so what kind?

Level: 49

I began really exploring the code base two days and I noticed that, obviously, it's pretty big, but that there was no documentation.

My prior coding experiences were with C/C++ projects that at the very basic level documented function prototypes in the header files, which was normally adequate. It would be nice to have documentation of namespaces, classes etc which give their usage, the file in which they are defined, extra comments etc.

I think we could also use some tutorials as documentation that do explain how fundamental things work, e.g. the things listed in the HACKING file.

Seeing as I'm new to the codebase I could add most of the documentation while simultaneously familiarizing myself with it, I'm new to C# though so I might get things wrong. Persons more familiar with the engine could add some tutorials, or I can do that when I read up a bit on it.

We also need to discuss what system we're gonna use for the documentation and what kind of nomenclature. The coding documentation should be in decent looking HTML, I guess.

Level: 52

Wiki?

I don't see much value in documenting classes, methods, etc. At that level of detail, things should be self-documenting, otherwise we've failed at writing clear code.

At a higher level, we should definitely write docs describing how the various subsystems work -- we often have a collection of traits which work together to provide a feature, etc. That's the stuff that's not immediately obvious from reading the source, unless you read the whole thing.

	Page 1 of 1