[ale] CLI conversion of word DOCs to PDF

[Lightner, Jeff]

It even makes sense to document BEFORE you do something.

Once I worked on a project where we were going to create perl versions of multiple scripts.   We were going to be using a new version of a product alongside the older version and were tasked with setting up new scripts with same name as they'd always had but which would work for the two different versions by dispatching out.

My team lead at the time forced me to first write a document about all the existing scripts, what they did, what parameters the allowed for and what the expected results were.   At the time I started I thought it was busywork that was keeping me from the real project.  However after having done it and we began writing the perl code it was amazing how easy it was to decide what to do having gone through the documentation exercise.

In general I'm a big fan of documenting things for two reasons:
1)  Some thing are only touched once in a great while and trying to remember something 6 months after you set it up is sometimes not easy.
2)  Being able to hand someone else a document and saying "here do this and ask me if you have any questions" saves a lot of time.  Also the questions one gets back can help to make a better document.





-----Original Message-----
From: ale-bounces at ale.org [mailto:ale-bounces at ale.org] On Behalf Of Jim Lynch
Sent: Tuesday, May 08, 2012 2:59 PM
To: Atlanta Linux Enthusiasts
Subject: Re: [ale] CLI conversion of word DOCs to PDF

On 05/08/2012 11:36 AM, Geoffrey Myers wrote:
> On 05/08/2012 11:18 AM, Michael Campbell wrote:
>>
>> On Tue, May 8, 2012 at 10:35 AM, Ron Frazier (ALE)
>> <atllinuxenthinfo at techstarship.com
>> <mailto:atllinuxenthinfo at techstarship.com>>  wrote:
>>
>>      I do believe that almost all programmers either can't, or won't, or
>>      perhaps most of all, are not given the time and encouragement to
>>      properly document their code.
>>
>>
>>
>> As a full time developer, "not given time" is the biggest issue I have.
>>    I'd love to have the time, AS I'M WRITING THE CODE, to document what
>> the hell I'm doing, but alas, so many in various levels of non-technical
>> management don't see it that way;
>
> Personally, I see this the easiest way to do it.  Commenting as you go
> adds very little time to the actual development process.  Particularly
> when compared to going back and trying to document the code after you've
> finished.
>
> But, I know what you mean about management.
>
I tend to agree, when I take the time to document what I'm doing, I'll
find I'm understanding what I'm trying to do better and make fewer
mistakes.  Otherwise I get lost once in a while.  Now if I could just
get my wife to understand that when I'm worrying over a large chunk of
complex code, I don't need to hear what her mother bought yesterday.

And duck.

Jim.
_______________________________________________
Ale mailing list
Ale at ale.org
http://mail.ale.org/mailman/listinfo/ale
See JOBS, ANNOUNCE and SCHOOLS lists at
http://mail.ale.org/mailman/listinfo




Athena(r), Created for the Cause(tm)
Making a Difference in the Fight Against Breast Cancer

---------------------------------
CONFIDENTIALITY NOTICE: This e-mail may contain privileged or confidential information and is for the sole use of the intended recipient(s). If you are not the intended recipient, any disclosure, copying, distribution, or use of the contents of this information is prohibited and may be unlawful. If you have received this electronic transmission in error, please reply immediately to the sender that you have received the message in error, and delete it. Thank you.
----------------------------------