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 w…

Accepted Answer

IMO you need both API documentation and plenty of examples.

You might get some mileage out of documenting your code of course, but if you're truly writing a system properly, your clients will never see your code. (That goes for clients in the calling sense, not necessarily in the "paying for your services" sense).

That's a fundamental of good practice and SOA, so you should really discard the "self documenting code" approach.

An alphabetic list of functions/methods/properties/whatever has value once the client has "got it" but until then, it's not immediately useful.

So that leaves you with having to showcase your creation. Give a bunch of immediately useful examples that demonstrate the kind of thing you envisaged. Make sure you have a simple example that demonstrates every function in its basic form with minimal interaction with the rest of the system (too many required interactions and you've probably not got a clean system anyway).

Once you have that, put it on a Wiki and encourage your users to enhance it. Consider using something interactive like a Stack-Overflow-like platform. MSDN is a good model but their examples often suck and can lack context. You might have the luxury of having more tight and specific uses than, say, the entire .NET framework. Early response to questions and updates to your examples/documentation will ensure your message gets across in the vital early days. This will help your documentation burden tail off quickly by looking after your clients and giving them useful, practical help.

Hope that helps.

How to share code documentation for a project?

Solution

Problem