What could be some pitfalls in introducing a style guide and documentation generating software in a development team?

Question

I'm considering using appledoc, a flavor of Doxygen for use in generating Objective-C code documentation, in order to create documentation for my company's iOS apps. The idea is that a server will generate the docs on a post-commit hook, then publish the documentation on an internal network.

Right now we have very little documentation of any kind, even comments in the code itself, so I'm expecting I will have to ask people to begin writing more documentation as they code. In this vein, I will also collaborate with my team in order to create a "style guide" for Objective-C code (like Google's), which will lay down some ground rules on how to write and document code.

What are some potential pitfalls in the above plan? Are style guides effective? I see the benefits in adopting a coding standard, but will developers find it restrictive? And do documentation projects such as this one work? And if not, why do they fail?

(I've posted on Stack Overflow a few times with moderate success, but this is my first time posting here. Please let me know if I could improve my question in any way. Thanks!)

Answer 1

Elements to take care from process and cultural point of view:
1. Ensure that expectations are well set for what should be the content in documentation It is important to define what is expected to be written when documentation is done. Many a times it is surprising but people make internal assumptions. Useless comments are just as bad as no comments.

2. API specific documentations is usually not all of it
Most often API specific documentations are great for black-box module to module integration and allows integration of complex system as they evolve. However, it is no substitute for key elements of documentation such as overall architecture, detailed designs or module designs, algorithms, functionality and business rules.

3. Ensure people buy in prior to enforcing it.
True success in any process is achieved only when there is a commitment from people to achieve it. It may be possible to declare it as a policy and people might even follow verbatim for the sake of it, but it wont bare fruits unless it is done with right spirit.

4. Take up people's involvement and agreement before freezing the exact standard
Coding styes always helps; and no one would deny that. However, it does call for a change when when there is a difference between what one personally follows and what the policy says. So it is best to see what most people are already fit with and define the rules where there would be least damage. Also, when people see that a certain coding guideline was selected due to majority thinking they are more likely accept the change rather than a committee imposed rules.

5. Monitor and adapt
Nothing is perfect on day one when it begins. Keep some basic expectations of what would you have expected and track if things are happening that way. When things are not tracked, even good initial successes fades away.

** For more See this

Answer 2

@Dipan's answer covers the main points, but there is a thing you need to do with this kind of cultural change: start small and experiment . Start with a very small project. One with people you already have on your side. People who loves documenting, using documentation tools, and more generally trying new things. Make them debug the process, and ask them to write feedback. Once you have something working with 2-3 programmers, you can try to bring the change.

It may take time, but it is necessary in order to defing exactly what are your needs, and whether your project fits well in your environnement (tools are easy to set up and manage? are people really using the doc? Does the process of writing the doc helps people to formulate their idea? do you want other team to access your documentation? etc)

Answer 3

If you have the budget, I would hire a writer. We're called programming-writers and can take over ownership of the project. I am working with a Seattle-area company who is doing Android work and have similar issues. A style guide isn't a bad idea, but I would strongly recommend giving concrete examples of good docs. I would also tread lightly with feedback. Too much negative feedback will only discourage those who already are reticent to expose their less than exemplary writing skills.

doug