minor Ramblings on Documentation
Project documentation can not be over emphasized I think. One of my worst nightmares came upon me while at work today… namely: The only one that understands the code is the guy that built it. L
Not very good. What we’re trying to do at work now, is to include a document that gives a high level explanation of the overall workings of the code. The last time we discussed this, there were lots of talks about UML diagrams, Use Cases, Object Relationship diagrams… phew… the whole works… well… I think they’re all cool, but I have some beef against them.
Some of them take for granted that you’re working with an OOP Language that has all the bells and whistles… classes, interfaces, inheritance, polymorphism. Well… I may be wrong, but I think in so doing, they are limited to only truly defining problems solved with these languages. Presently, I work (by day), in a mostly .NET outsourcing company (tho, we’ve been expanding recently, I guess due to guys like me self J uhh… who am I kidding? ), so it would seem unnatural for me to critique these tools with this particular line of thought.
Well.. why I went in that direction, is that I KNOW from experience that not all problems are best solved with OOP languages… so a better method of documentation SHLD capture non OOP based solutions. If a method exists that can do this, its probably a better method of documenting code.I probably need to read more about UML and the rest, but right now, I think Eric Raymond’s Advice resounds in my ear really loudly, “By All means… be textual”.
This I believe has its pluses and minuses, for instance we all know that a picture can be worth a thousand words. I think a neat way would be to combine them neatly.
I favour textual because it mostly forces the developer to think about the implementation and then describe it in words… there’s in my opinion no better way to reflect on something you’ve done, than writing about it. Diagrams should be used to describe areas that would really benefit from using diagrams too. As you can see this approach doesn’t really have a name, but its simple and doable (I think…)
With this approach too, problems solved by Functional thinking can be described fully… and also norminal imperative approach is not left out. And probably more important, is that the implementation idea is conveyed, not the nitty gritty of the implementation which should be apparent in good written source code.
In conclusion, I’ll say, ofcourse, I may be blind to many existing facts, since I’ve not researched this, and I’m just writing after a hard days job, but why I think its important is that this is field experience… as opposed to theoretical stuff… so maybe there is something of importance afterall in what I’ve just said.
Just ramblings from a guy trying to get better at his job, and make life easier from those who come after him.