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.

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

put on hold as off-topic by MichaelT, durron597, Snowman, Dan Pichelman, GlenH7 Jul 24 at 21:20

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to recommend a tool, library or favorite off-site resource are off-topic for Programmers as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it." – MichaelT, durron597, Snowman, Dan Pichelman, GlenH7
If this question can be reworded to fit the rules in the help center, please edit the 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

2 Answers 2

up vote 9 down vote accepted

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.

When I was at The Motley Fool, we had 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 git to navigate through the code when we're on the internet (makes code reviews go smoothly)
share|improve this answer

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

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