Thinking Out Loud and Pinging the Web
I was worried that my Software Engineering class this semester would be analogous to my undergrad Economics for Engineers class, but now I think it has the potential to rank as one of my favorite classes (though I maintain that it also, as a topic, has great potential for being analogous to my Econ class; the instructor and the other students seem determined not to let that happen though ^_^)
Anyway, as I was doing the reading for tomorrow's class, it mentioned the importance of meticulous documentation of design decisions (e.g. why you decided to go with a specific type of class, or why you decided that a certain method should go in a certain place, or whatever). I can see why it would be important to keep a record of such decisions; you might come across some other aspect of the design down the road that tempts you to change your mind, for example, and if you can refer back to that decision, then you can say, "Oh, right, if I did it that way then these three other things would break," or "hmmm, well, this new discovery means that the reasoning behind this decision no longer applies, so we can change it because it would be better--for whatever reason--to do something else," or whatever. Or you hit a dead-end, and want to be able to essentially walk backwards up to the decision tree and try to find the one that set you on the path to being stuck (sort of analogous to reverting to an earlier version of a file or baseline in a version control system) instead of having to start all over.
Well and good; I am reasonably convinced that documenting design decisions is something that ought to be done. However, I am also strongly convinced that one often-overlooked aspect of such documentation is that it theoretically will need to be referenced at some point in the future, and that the person doing the referencing is almost certainly not going to have the inclination or patience to read through the entire document trying to find the relatively small portion that is relevant to the matter at hand for them.
Does an effective method exist for tracking such things as design decisions? Are there tools out there to facilitate this? It seems like tagging might be able to offer some help, but I don't know. Similarly, does it make sense to keep such documents in plaintext (or maaaaayyyyybe HTML) and track them in a version control system? Is there such a system specifically for such documents?
If there's not, but you were given the opportunity to provide input on a design for one, what features would you want it to have?
Is this a problem that can be solved by such tools, or does a methodology or discipline need to be developed as well and then applied in order to really work? Does such a discipline already exist?
Disclaimer: Yes, I am tentatively entertaining the notion of trying to actually build something like that if it does not already exist. However, the odds of this actually happening are rather small, given other projects currently taking up my attention (such as the aforementioned class; something tells me that this undertaking would be bigger than makes sense for a semester project ~grin~). On the other hand, if I suddenly find myself between projects, and nobody else has actually put something together by then, I might have a go at it and it would be great to know what other people would want to see in it as well as my own ideas of what would look good.
Or maybe I'll just learn Lojban ~wry grin~
Anyway, as I was doing the reading for tomorrow's class, it mentioned the importance of meticulous documentation of design decisions (e.g. why you decided to go with a specific type of class, or why you decided that a certain method should go in a certain place, or whatever). I can see why it would be important to keep a record of such decisions; you might come across some other aspect of the design down the road that tempts you to change your mind, for example, and if you can refer back to that decision, then you can say, "Oh, right, if I did it that way then these three other things would break," or "hmmm, well, this new discovery means that the reasoning behind this decision no longer applies, so we can change it because it would be better--for whatever reason--to do something else," or whatever. Or you hit a dead-end, and want to be able to essentially walk backwards up to the decision tree and try to find the one that set you on the path to being stuck (sort of analogous to reverting to an earlier version of a file or baseline in a version control system) instead of having to start all over.
Well and good; I am reasonably convinced that documenting design decisions is something that ought to be done. However, I am also strongly convinced that one often-overlooked aspect of such documentation is that it theoretically will need to be referenced at some point in the future, and that the person doing the referencing is almost certainly not going to have the inclination or patience to read through the entire document trying to find the relatively small portion that is relevant to the matter at hand for them.
Does an effective method exist for tracking such things as design decisions? Are there tools out there to facilitate this? It seems like tagging might be able to offer some help, but I don't know. Similarly, does it make sense to keep such documents in plaintext (or maaaaayyyyybe HTML) and track them in a version control system? Is there such a system specifically for such documents?
If there's not, but you were given the opportunity to provide input on a design for one, what features would you want it to have?
Is this a problem that can be solved by such tools, or does a methodology or discipline need to be developed as well and then applied in order to really work? Does such a discipline already exist?
Disclaimer: Yes, I am tentatively entertaining the notion of trying to actually build something like that if it does not already exist. However, the odds of this actually happening are rather small, given other projects currently taking up my attention (such as the aforementioned class; something tells me that this undertaking would be bigger than makes sense for a semester project ~grin~). On the other hand, if I suddenly find myself between projects, and nobody else has actually put something together by then, I might have a go at it and it would be great to know what other people would want to see in it as well as my own ideas of what would look good.
Or maybe I'll just learn Lojban ~wry grin~