Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

We've currently got a small team of programmers (3 people) but are expecting to add more soon and are starting to keep documentation on things that need to be interacted with a lot, or reusable generic classes we've written.

Originally we were storing all this information on writeboards @ backpack, but it doesn't support code highlighting or much other formatting.

My current choice has to been to install Media Wiki along with a javascript based syntax highlighter and it seems okay except for lack of being able to put things in a nested structure (the plugins I've found are either broken or too lacking in documentation).

While this solution seems suitable now, I'm wondering what other approaches other teams take to storing/organizing large amounts of documentation to an ongoing, ever growing project.

share|improve this question
    
For my .Net libraries, I like to use Sandcastle . Its terrific for generating MSDN style documentation. –  Morgan Herlocker Apr 27 '11 at 15:19
add comment

2 Answers

Don't try to maintain two separate systems of documentation. It never works.

If you're using a language with Namespaces, then your classes and namespaces should be well named and in the Ubiquitous language of your domain.

If your favorite programming language allows you to generate comments from code, then you should use that. Wikis are good for things that don't have to do with code: Guidelines, procedures, the 'meta' stuff. For anything that concerns documenting the code or its intent should be done in code.

At The Motley Fool, we have the following:

  • A Scrum of Scrums, where we share information with other teams.
  • A 'tech fair' once a month where each team demos what it's working on (generally while we're all munching on Pizza)
  • An intranet portal for collaboration running SocialText - Which contains a Wiki for checkin procedures, files for Visual Studio settings, and other things
  • The intranet portal also contains 'discussion groups' where we document happenings in the online world (like Twitter, but with permanence).
  • A page that lists all of the internal websites we use.
  • We use Grok for Subversion to navigate through the code when we're on the internet (makes code reviews go smoothly)
share|improve this answer
add comment

We use http://sphinx.pocoo.org/.

It has code highlighting and can pull documentation from the source.

It works most easily with Python, but has modules oriented around other languages.

The best part is that ReStructured Text (RST) is very lightweight markup and your documentation is simple source under simple source-code control.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.