How do you/your company create project-documentation?

Question

I know, it is hard to document on the work you already do. Especially time-constraint project often miss good documentation.

Do you or the team you work in have some tricks to create some project-documentation? What are your best-practices?

Answer 1

At our company we make bad project-documentation, because of lack of time. But one thing we discovered worked:

We developers meet every Friday to have a short talk. Every time we decide at the start of the week, who is talking this Friday. The content is differing, but often it is about the current project and often it start with explaining the goals of the project and ends with diving into some code-examples. We always record this sessions and create screencasts. The archives of this screencasts are some rudimentary project-documentation.

Answer 2

For us it starts with a Word Document. You basically build out a bulleted list of things you want to accomplish. Then those bulletpoints get transformed into more specific details (classes with members, methods, and properties). For bigger projects we can spend a week or two, or three writing the actual specification before the first line of code sees the light of day.

Once we think we have a final draft we fire up our IDEs and write the interfaces. Documentation is done inline in Visual Studio. We don't document every little thing but we try to keep on the ball about it.

For small projects it's still good to do the documentation and specification done, you never know where it might end up. We wrote a little tool to test some of our classes and it has blossomed into its own testing suite for our developers. We didn't think it was important at the time but without good documentation it would be unusable at this stage.

Answer 3

Use a good documentation generator like Javadoc and ensure your developers use it. It doesnt take 2 minutes to leave a comment indicating the parameters, return value and exceptions a method has and it can save you a lot of time when you come back to the code later.

Answer 4

For us, it all starts with a BRD (Business Requirements Document). From that BRD, we assembly very lightweight technical documentation consisting of simple flows, implementation guidelines, and (recently) predefined interfaces which the developers will inherit from - the goal being that all public members of any classes developed will have at least initial documentation in the form of XML Comments. Note that we are a .NET shop, so a lot of what follows is specific to .NET.

From there, we rely on three major components to create rather thorough API documentation. First is GhostDoc, which we use for XML Comment inheritance (from the aforementioned interfaces) and autogeneration of new members. We use Sandcastle for the actual assembly and presentation of the documentation, using Sandcastle Help File Builder as an IDE to set the documentation properties and add additional, non-comment derived documentation.

We additionally are in the process of incorporating the documentation generation as part of the build process so that the most recent version is always available.

On top of that we use Team Foundation Server, so we use the available wikis, discussion boards, and other features of the Team Project in Sharepoint to collaborate and share information.

Answer 5

Best practice: use a wiki for project documentation.

Wiki's have specific features for multiple people - change history, comments/talk, recent activity/updates page. Perhaps most importantly, wiki's tend to make updates easier, so the documentation is more likely be up-to-date given the usual time-pressure.

Answer 6

Code reviews help tremendously. It will help you figure out where your documentation needs to be improved if it's lacking.

Answer 7

It varies for us. Usually there's some form of Javadoc-esque system involved for API documentation - Luadoc for Lua code, or Doxygen for C/C++ sources (those are our two big technologies). We also have a wiki for documenting ideas, goals, timelines, etc. But since we're only a very small handful of developers, it's not difficult for us to stay on the same page, since our jobs overlap so much.

Answer 8

Project Documentation really isn't all that hard. It's just an alien thing to many developers. Thankfully for me before I took my degree in Computer Science I trained in Computing, involving such things like Project Management and Quality Control. The problem with documentation is that it is not coding. Programmers are paid to think and program. To most programmers documentation is writing about a business project, something that is boring.

First of all, decide which standardised documents you'll be using and who needs to write what. Secondly, ensure that developers write and keep hold of all information that they use. From then on the documentation has already crudely written itself. Of course with many methodologies there is documentation that needs sorting out before you begin (Project Initiation Documents and the like) but you have people on staff that are capable of writing whilst they have free time so give it to them! As long as developers keep notes you'll have no trouble with getting content for your documentation. Formalising this information will not take that long.

Next time you're coding, leave a text file open or pick up a piece of paper and jot down what you've been up to. Given ten minutes at the end of the day you can easily recall what you've been up to and write that stuff up.