> To turn things back around somewhat, what happened to the > write documentation first, then write the source from the > documentation? If something needs to be added (and who > knows of a program where it doesn't?) then document it > first?
As with most things in life, it depends on the situation. Try doing that in a Boston area startup company and the company will be out of business in a heartbeat. I worked in a company along the 128 belt sometime around 1995. They had precisely 2 weeks worth of reserves to pay employees in case a sale didn't come through. When you're running on that kind of margin you need to have turnaround within days of a sale. When I worked for a finance company, of middling size, they bought and sold smaller companies on a monthly basis. It was all finance, but the models were all different. A company bought one month might be sold by the next quarter. Documentation was a waste in that environment. I can concede that a company with an already solid business and a relatively static business model would benefit from the document first approach. Repeating what I said at the top, it depends on the situation though.
> As I understand it, this was one of the prime tenets > behind literate programs like weave/tangle.
As I mentioned in another response within this thread I have no knowledge of Literate Programming but feel it would be worth my time to read up about it. I'll take from it what I feel is worthwhile and leave the rest behind.
> Also, how does this contrast with the "only document > what's needed" mindset that most programmers end up in, > because there's literally no time to do anything else? At > what point does practicality kick in?
I hate arguing against a fictitious group. I'm not willing to concede that most programmers end up in that mindset.
My experience is that documentation is devalued by the organization. Managers are willing to talk at great lengths about the importance of it but I haven't experienced many who were willing to postpone implementation dates so that solid documents could be written.
From my experience alone, I think that "living" documents are the only worthwhile ones. By this I mean documentation in the form of wiki's. Documentation should be a simple process devoid of any back-and-forth in committee approvals. I'm in the middle of that now. Sometimes it's a week before I hear back from a single committee member. By that time, I've lost interest in what I'm doing.
Practicality is very relative depending on your mindset. You'll have to be more specific about what you think is practical in this instance.
Flat View: This topic has 38 replies
on 39 pages