Well, I managed to get myself into that play I auditioned for last week. So, when March exposes it's lovely, birthday-laden self on the calendar, I'll be performing in The Full Monty at the Lincoln Community Playhouse.
It might be a little nuts of me; the show will be quite a bit different from what I've done in the past. Somehow, my high school one-acts and the few musicals I've been in since haven't exactly required the balls that one might need for this show. Regardless, I'm looking forward to it. It'll give me something somewhat productive to do in the evenings (even if that is just making an ass of myself), and will hopefully provide me some new blood for my social circle.
In any case, I encourage people to come see it, if only to get some butts in the seats, but I will warn you in case you didn't know--I'm gonna be naked. So add that into your considerations.
Monday, January 22, 2007
Tuesday, January 16, 2007
documen-tedious
We use a wiki for our project management and documentation at work; it fills the role fairly well, and is in principle pretty agile and can be easily changed. In principle.
In practice, editing the wiki is perhaps the most tedious documentation work I've ever done. It isn't the sort of download-and-fill-out-the-template documentation that was so prevalent back in the JDE days--no, this is a continuous, constantly impending job of having to go through the free-form wiki, wrangle it into some sort of organized form, and update the appropriate pages, which may or may not still be linked in the right way. The wiki we're using (Trac) doesn't allow for spaces in the names, so page names aren't exactly English, which makes it harder to link the pages together in the ways I would like; it interrupts my flow to have to redirect and name the links with the built-in wiki formatting rules.
All in all, I'm not too pleased with it. As important as I think documentation is, it should be like an extension of the project, not an entirely new project all its own. Developers are already basically trained to always put in detailed log messages in their commits (at least, we are around here), so why can't the documentation be like that? Granted, we've already got some sort of bastardized Javadoc going on (which doesn't work well; our JavaScript is formatted differently than the generator expects) but that doesn't (and as far as I'm concerned shouldn't) explain the logic, the business rules, the connections to other components, etc. The Javadoc is for the API--what goes in, what comes out, which functions the object has--but not the purpose in the greater project. That's the sort of thing that should be first determined in the design, documented as such, and then updated with implementation-specific comments that change as the implementing class changes.
So, here's my idea for a solution:
In any case, I wish I had something like that; it would improve our documentation and (as far as I can guess) would not slow us down much in development. Plus, with its similarity to the commit logs, it would be easy to accomplish the required social engineering to get everyone to actually document their changes. I don't really have the time to develop it right now, but maybe someday...
In practice, editing the wiki is perhaps the most tedious documentation work I've ever done. It isn't the sort of download-and-fill-out-the-template documentation that was so prevalent back in the JDE days--no, this is a continuous, constantly impending job of having to go through the free-form wiki, wrangle it into some sort of organized form, and update the appropriate pages, which may or may not still be linked in the right way. The wiki we're using (Trac) doesn't allow for spaces in the names, so page names aren't exactly English, which makes it harder to link the pages together in the ways I would like; it interrupts my flow to have to redirect and name the links with the built-in wiki formatting rules.
All in all, I'm not too pleased with it. As important as I think documentation is, it should be like an extension of the project, not an entirely new project all its own. Developers are already basically trained to always put in detailed log messages in their commits (at least, we are around here), so why can't the documentation be like that? Granted, we've already got some sort of bastardized Javadoc going on (which doesn't work well; our JavaScript is formatted differently than the generator expects) but that doesn't (and as far as I'm concerned shouldn't) explain the logic, the business rules, the connections to other components, etc. The Javadoc is for the API--what goes in, what comes out, which functions the object has--but not the purpose in the greater project. That's the sort of thing that should be first determined in the design, documented as such, and then updated with implementation-specific comments that change as the implementing class changes.
So, here's my idea for a solution:
- The documentation should stored in a wiki, which should be filled out with the initial design descriptions.
- The pages of the design wiki (through macros or something) could be linked to files/classes in the repository which represent the implementation of that design element, which will have their API reference generated directly from comments in the code (Javadoc, or something)
- The wiki could then be updated by a script/macro that reads markup entered by the developers as part of their commit logs any time a change is made that effects part of the documentation.
In any case, I wish I had something like that; it would improve our documentation and (as far as I can guess) would not slow us down much in development. Plus, with its similarity to the commit logs, it would be easy to accomplish the required social engineering to get everyone to actually document their changes. I don't really have the time to develop it right now, but maybe someday...
Monday, January 15, 2007
irregular expressions
Sometimes I'm jealous of people who engage in the more "standard" arts as hobbies or professions--things like painting, photography, woodworking, writing, etc. Or, at least, "jealous" is the best way I can describe it; really, it's more a feeling of sadness directed at an unfortunate state of the world rather than at any person or field.
I'll try to explain; it's not that I feel that they possess some sort of faculty that I lack, or that they somehow gain an enjoyment of life that I am unable to attain. Art, in all forms, is a wonderful thing--not just for the observers (for whom it is sometimes not so wonderful; seen Ultraviolet lately?), but for the artist.
For me, art is primarily about creation. The artist takes some sort of raw material from the world--be it paint and canvas, steel and brick, or even just a subtle trick of light on a city street--mixes it with a portion of him- or herself, and delivers the finished product in all it's novel glory to the world (or anyway, that's how I think of it when I see something that stirs me).
Yet, this sort of creation is not limited to the "Arts". Sometimes, I feel the same feeling looking at an intricately, complicatedly tangled system of on-ramps and freeway exits as I do when I hear the Rohan theme in The Two Towers. Some civil engineer (or some few) designed that, built it, took the concrete and steel and added a dash of human will to produce something entirely new in the universe. It's the same with my source code, or an elegant math proof, or a novel argument for some philosophical concept.
Therein lies my jealousy, if that's what you can call it; what is it about the world (or just our society, or whatever) that robs practical things of their aesthetic value? Why is it so admirable to be able to design a living room, but not a word processor? Why are there television shows dedicated to competitions in fashion design, but not in architecture? Why America's Next Top Model, but no America's Next Top Modeler?
Anyway, that's my rant for the day. Too much Fountainhead, I guess.
I'll try to explain; it's not that I feel that they possess some sort of faculty that I lack, or that they somehow gain an enjoyment of life that I am unable to attain. Art, in all forms, is a wonderful thing--not just for the observers (for whom it is sometimes not so wonderful; seen Ultraviolet lately?), but for the artist.
For me, art is primarily about creation. The artist takes some sort of raw material from the world--be it paint and canvas, steel and brick, or even just a subtle trick of light on a city street--mixes it with a portion of him- or herself, and delivers the finished product in all it's novel glory to the world (or anyway, that's how I think of it when I see something that stirs me).
Yet, this sort of creation is not limited to the "Arts". Sometimes, I feel the same feeling looking at an intricately, complicatedly tangled system of on-ramps and freeway exits as I do when I hear the Rohan theme in The Two Towers. Some civil engineer (or some few) designed that, built it, took the concrete and steel and added a dash of human will to produce something entirely new in the universe. It's the same with my source code, or an elegant math proof, or a novel argument for some philosophical concept.
Therein lies my jealousy, if that's what you can call it; what is it about the world (or just our society, or whatever) that robs practical things of their aesthetic value? Why is it so admirable to be able to design a living room, but not a word processor? Why are there television shows dedicated to competitions in fashion design, but not in architecture? Why America's Next Top Model, but no America's Next Top Modeler?
Anyway, that's my rant for the day. Too much Fountainhead, I guess.
Friday, January 12, 2007
it beats a dead horse...
Despite my previous enthusiasm, it turns out I will not be going to Ireland this year.
Instead, Allied Strategy (my current employer, for those few of you don't know) made me an offer that I was unable to turn down. So I guess I'm going to be staying in Lincoln for a while (at least another year) and doing everything in my power to help the company make lots and lots of money.
Anyway, that's a happy development. I can just put off my international travel plans by one year, so no big deal.
And I'm auditioning for a play. Just thought you should know.
Instead, Allied Strategy (my current employer, for those few of you don't know) made me an offer that I was unable to turn down. So I guess I'm going to be staying in Lincoln for a while (at least another year) and doing everything in my power to help the company make lots and lots of money.
Anyway, that's a happy development. I can just put off my international travel plans by one year, so no big deal.
And I'm auditioning for a play. Just thought you should know.
Subscribe to:
Posts (Atom)