[mythtv-users] OT: Documentation?!?! (was Re: MythFrontend 0.21: What is a watch list?)

[Jon]

On Mar 12, 2008, at 6:55 AM, Andrew Close wrote:

> On Tue, Mar 11, 2008 at 9:15 PM, Brad DerManouelian
> <myth at dermanouelian.com> wrote:
>
> <snip/>
>
>>  My point is that if dev spent 1/3 their time writing doc instead of
>>  coding and fixing bugs, we'd have only 2/3 of a complete system.  
>> Tons
>>  of people complained that 0.21 took so long to release. Imagine if
>>  they had to wait for dev to catch up on doc as well.
>>
>>  Also, OpenSource is the only type of software development process  
>> I've
>>  ever seen where developers were expected to provide end-user
>>  documentation. The software companies I've worked for would fire any
>>  developer who tried to give doc to end users without going through a
>>  tech writer.
>>
>>  Please don't point out where I'm clearly wrong and that other
>>  companies have dev write doc. I'm speaking from my personal  
>> experience
>>  of the admittedly short 8 years working for software companies.

I must say, you are very lucky to have a competent technical writing  
staff. (I presume they're competent, maybe that's my mistake)

>
> Brad, you are clearly wrong*.
> i've never worked on a project that had dedicated tech writers, and i
> have worked at some big companies on fairly large projects.
> documentation has always been in the domain of the developers and is
> almost always a /required/ part of the development process.  however,

That's the way it works at my company, you wrote the code, now  
document it so that we can support it. I work in the 'Incident  
Management' department, and I gotta say, our documentation SUCKS.  
This isn't the programmers faults though. Half of them speak english  
as their second language, and all of them spend most of their days  
writing in the Java (I STILL can't understand who thought THAT was a  
good idea) and C.

> more often than not, timelines are immovable and something has to give
> so documentation goes out the window. :)  actually, at my current
> /job/, timelines are set before business requirements are drafted.

I would like to say something witty now, but honestly, all I can say  
is that you're not alone. This is the other problem with  
documentation at my place of work. Except at my business, not only  
are the timelines immovable, they are completely baseless. They spend  
2 or 3 years talking about doing it, discussing the possibility of  
it, the practicality, etc... , and then one day they come in and tell  
you, 'you have 3 months to deploy this.'  Yanno, they couldn't  
possibly have told you 3 years ago, we're going to do this, and then  
spent the next 3 years bickering about it while you actually had time  
to test it. (in this case I'm referring to a thorn in my side that is  
called Magic, and bay is it magical. Who exactly writes a Web Based  
(but IE only) ActiveX powered trouble ticketing system?)

> development is typically done before the conceptual design is
> reviewed, technical design docs are an after thought if they are even
> thought of.  and while we do have a very good and competent QA staff,
> QA always suffers due to the time restrictions set by sales people and
> upper management that don't have a clue about what it takes to develop
> software or add new features to an already extremely cobbled together
> system.

Oh, but they don't need to know all that stuff. All they need to know  
is what the final product has to do, and when they want it done. The  
details are for the lesser paid peons to figure out.

> ok, this was supposed to be an over exaggerated, super sarcastic
> response and now it's looking more like a rant.  so much for being
> funny...

It is funny. But it's funny because these are the businesses that are  
running the country right now, and people can't understand why  
there's problems.
Meh, maybe it's less funny, but I just got home from work, and it was  
a nice rant.

> *and by 'wrong', i mean completely on the mark ;) (or maybe a tad  
> off center)