How to share code documentation for a project?

Question

There was a similar-ish question here on SO https://stackoverflow.com/questions/9475795/how-do-you-share-code-across-teams-working-on-very-different-projects but mine is about writing documentation.

Scenario:

Let's say my team is working on a software project, a Fany-WordPad like application which has a feature called Fancy-Word-Art ( just like MS Office's word Art). Now I wrote the code for the main window( using WPF in .Net, or using Window Builder in Java, doesn't matter which tool/language).

Now if my colleague Mr Spongebob is writing the Word-Art part, how would I tell him what functions to call / Api to use to draw on my window? i.e. How do I let Mr SpongeBob know that he needs to call GetWindow() method to get a reference to the drawing surface, the parameters he needs to pass along , and so on?

I hope I am being clear here. Is this the procedure?

Step 1 : Use your company wiki site to understand your colleague's written code

Step 2 : Write the GetWindow() method so that it works well with the rest of the project

Step 2 : Now put a wiki on your intranet with the method parameters/ data type requirement for your GetWindow() method or use Doxygen/ Confluence as suggested below

Step 3 : Now its your colleague Mr Spongebob's headache how to find how to draw his word-art on my window.

This just doesnt sound right .. With tons of functions, Spongebob's life will be hard, just as mine. Both of us rummaging through documentation to find the right functions to do our job. What if then I change GetWindow() to GetWindow(string title).. Now how do I literally tell the poor spongebob he needs to redo his code.

Am I missing something here? Please share your experience, how do you tackle this problem in a real world software house environment? If your fellow developer is on the next table , do you actually show them how to implement a certain method as they get stuck, or how do you deal with this situation? thank you

Thanks

Answer 1

A good question. Of course i do not have the universal solution. Code documentation in msdn/sun style is a good base. But for concepts, architecture and so one you need more than this. In some projects we use wikis for that. For customer requests, we have a kind of ticket-system where we also store some (no-code) information to solution. All in all there is no central place for all the documentaion stuff.

Edit: Your code in self is often the best documentation, following clean code guidelines or something else is a real best practice :-)

Answer 2

Wikis are a cracking idea (good suggestion @Micha!). I used to use one in a previous company for a large engineering software/hardware project. It obviously spanned hardware and software guys and so it was a great way to share info across all teams. It's really useful if it's a long term project too - you can keep track of changes to functionality/API as things inevitably morph over time.

We used a paid service - Confluence if I remember rightly; but there are free wiki hosting sites too e.g. wikihost (just a quick google search, I can't vouch for them).

On another note though - have you thought about self documenting code at all? For example "Doxygen" or similar? Takes a lot of pain out of documenting every single function and also sets up a decent framework that can be padded out with more info where necessary. It also creates a nice UI for stepping through all the functions /class etc.

Edit: I've actually just started using Google Sites (sites.google.com) to create a wiki for a dev team I'm not working with. It's free (as in 'beer') and seems pretty good so far, although it does lack auto code formatting.