Documentation and API
For the last several years I’ve been consulting a big company in maintaining their flash framework. And as always when times get rough the first thing you omit is the documentation.. I myself have done this loads of times even if we have agreements that a new version isn’t ready to release unless it’s documented! They’re always allowed to be released.. both by me as the lead developer and the team.
It’s just too tedious too update that big ole document that you “know” nobody reads, and the ones that have been forced too read it doesn’t appreciate the updated document. Since there is almost never an easy way to see what sections has been updated and you’ll just have to read the whole thing again.. not likely right?!
But as an developer who has been on the other side of the documentation and actually can see the benefits of good documentation I strongly believe that there must be some form of information-passing between the developers creating a framework and the ones using it. And since it is just that, from one developer to another. Why don’t make the most of it and make sure that the other developers can’t miss your intentions and documentation. Even if they’re just opening the framework to see if they can make it run they instantly starts reading documentation. So how does one do that?
It’s both simple and not. The not so simple part is to write your code clean. Make the functions talk for themselves. Make them talky and intuitive. The more simple part of it is to comment your code with API-comments so that a tool can interpret the automatically generate an API as a part of the release. This way you read documentation whilst coding and if you find something you don’t quite grasp you’ll probably go to the API docs and try to see the bigger picture.
Now for someone who hasn’t ever heard of the framework, some sort of technical documentation would help. But this documentation should not contain any code. It should be 2-4 pages long and explain the whole picture and specific terminology of the framework. It is only allowed to be updated when a feature is added or removed. When updated, the concept of the feature shouldn’t have been altered. Just the implementation and that should not be reflected in the technical documentation.
Doing this would probably remove 95% of the questions about how to use the framework to the benefit of feature requests.