Sign in to follow this  
MMK

Documenting game projects

Recommended Posts

Hi everybody, I am looking for the right tool for the job. I have a number of large projects (in terms of components) that I want to effectively document. Currently, I have a packs of UML designs (MS Visio), comments in the source codes, and other documents like specifications, manuals, guides, etc... (Word documents). Now these do serve the purpose when we need to find out about something. However, maintaining these descrete elements is becomming an overwhelming task as the size of the projects (and group members) increase. I have tried some utilities that generate help files from source code comments, and they seem to help in keeping things syncrhonized, but most of them were quite limited and requried specific commenting styles to recognize. What I need is some expert recomendations from veterans that have worked on large projects and have been through this. Recommend tools, best practices, or anything you believe would help. Thanks for your time...

Share this post


Link to post
Share on other sites
Requiring that your contributors use the commenting style for Doxygen is usual on large OpenSource projects.

However, what we did at work, is run the source through a script which turns all comments in header files into Doxygen comments, before building the docs from Doxygen. "//" turns into "///" etc. We still have to use \param and \see to get the extra nice formatting, but even if we forget, the output of Doxygen is pretty useful.

Of course, you can't expect documentation to solve the entire comprehension problem. At the core, a programmer on a large project needs to be able to dive into the code, figure out how it works, and write tests that reproduce a bug before fixing the bug; then use the test (and previous tests) to prove the bug was fixed, as well as no regression introduced. New features are just like bugs, except bigger :-)

Share this post


Link to post
Share on other sites
Thanks for the quick response. I wonder though, how do you manage to synchronize the code with the Doxygen output after the initial build. Do you use scripts that only convert the style to Doxygen temporarily before the build, and use it every period of time to rebuild the documentation? Or did you permenantly change the style to Doxy's for good just once?

What about non open source projects? Would you recommend something else for these?

Share this post


Link to post
Share on other sites
MMK, try looking at a Wiki system, such as MediaWiki. These are great for intrateam knowledge management and dissemination, when automation is not required. We are currently using MediaWiki for all internal communication tasks both on my day job and in Software Species.

As for other cases, when you have to deliver documentation with the product, there is a wide range of possibilities - single-source systems like AuthorIT or Docbook, professional tools like Adobe Framemaker, and traditional vehicles like Microsoft Word. It all depends on how much flexibility you need, on what you need to deliver and to whom.

As for Doxygen, yes, you need to rerun it after you have updated documentation tags in the code.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

Sign in to follow this