Editing… No longer a workplace fear.

Throughout my career I have been tasked with creating, reviewing, and editing documents. Prior to taking this Technical Communications class I would have given myself an A for creating documents, a B for reviewing documents and a D for editing documents created by my peers. Because I have always struggled with editing, I spent quite a bit of time on last week’s readings and assignments.

In the past what I thought was editing was a critical review of a document that didn’t include the 4 levels of editing approach. The results of this type of editing left a lot to be desired and really didn’t help the document creator. I typically only found major gaps in information and flaws along with the typical grammar and punctuation mistakes. Really all I was good at judging was overall professional appearance.

I found myself being overwhelmed when someone would ask me to edit his or her work. Because of my nature, I struggled to compartmentalize their work and often would just rewrite the entire document in my own words instead of editing the words that were already on the page. In hindsight, I can see how this was ineffective, a waste of time, and could be viewed as offensive.

The 4 level approach to editing helped me lay out a compartmentalized approach to editing documents created by others and myself. Using this approach I read the document focusing on only the context of each level and not thinking about the document as a whole. This process allowed me to provide substantial feedback on the document as opposed to just re-writing it to my standards. This is a process that I will utilize for the rest of my life.

Overall this class has been very useful for me. The tools I have learned have strengthened my technical writing abilities and will help me to continue to communicate technically and through the use of technology. Lastly, this class has taught me technical communication isn’t just about the people who will follow the procedure or read the document. I need to keep the secondary and tertiary readers in mind as well.

Work Documents or How I Learned to Stop Worrying and Love Organization

Before taking a technical communications class, I never though much about how documents I created were designed, especially at work. At work, when I wrote stuff, it was usually just for me and maybe a co-worker. I would just list steps for preforming tasks, and it wouldn’t really look neat.

Making a document look pretty/presentable isn’t really that hard. Breaking up instructions into sections and cleaning up the language makes it easier for the next guy to understand it, versus me having to explain everything.

So, moving forward, I’m going to make my documents look cleaner and more well organized. It’s not too hard, and it even makes it easier for me when I am re-reading them weeks or months later.

This class has also shown me that editing/proofreading is only a small part of reviewing a document. There is more to it. You need to make sure the design is laid out so that the “target audience” can easily follow it. In my case, the audience has always been myself or my co-workers (who are also programmers), but I have had to send things to my boss that have used language he might not understand (as he is not a programmer).

-Eric aka ens3261

Obtaining Data Center Access for New Employees and Vendors

I have chosen to discuss this process mainly because it has been a significant thorn in my side over the past couple months. The process is an essential step in the onboarding process for any new employee or vendor working on my team. Because a substantial portion of our jobs require physical access to multiple data centers it is important that new employees and vendors have access to these locations on their first day.

For me the process begins when my Director notifies of a date when a new employee or vendor will be starting work. This notification often comes via email and will include the name of the individual and their employment information. Also included would be the name of the company they work for if they are a vendor.

Once I have the important information I then have to print out a form that needs to be filled out for our office administrator. This form is attached to a copy of the picture taken for the badge and filed in the building that has the datacenter in it. I then have to print and fill out another form that goes to the corporate office down the street that is used for fingerprinting and the actual production of the badge. Finally I have to fill out an electronic ticket in our company’s internal ticket system for our Critical Infrastructure team to review and approve access for the new employee or vendor. This ticket often requires additional information that isn’t included in the initial request from my Director. When this occurs I am forced to use generic numbers as place holders so the ticket can be created and access approval isn’t delayed. Once the missing information is known I can go in and edit the database so our notification systems are properly updated.

If all goes as planned when it is the employee or vendor’s first day I then have to take the hand written paperwork along with a hard copy of the Critical Infrastructure team’s approval first to our office admin and get the individuals picture taken. This is a digital image and is shared with the corporate office admin down the street.

When I have confirmation that the badge has been made and access has been established I have to take the new employee or vendor down the street to the corporate office. Here submit the second document and another copy of the Critical Infrastructure Team approval and the individual gets finger printed and is given their badge.

The final step is to take the new employee or vendor to each office and data center to verify access and give them a tour. This wasn’t always required but human error during the badge creation process occurs too often and if the error isn’t detected within 48 hours, we have to start the whole process over again.

 

This process is extremely tedious and bulky. In my opinion we shouldn’t have to use physical documentation at all during this process and everyone should work off of the Critical Infrastructure Team’s Ticket.  By working off of one ticket that has the same information that is hand written on forms less waste is created and the process is cleaner and more efficient. Additionally I don’t understand why the same person that creates the badge can’t be the one who takes the picture. In my opinion I feel the Critical Infrastructure team should own the entire process but for various political reasons that isn’t possible.

Managing Code Between Repositories

One of the processes I go through almost every day at work is deploying our code base to the test (or sometimes the production) server.

We use SVN for our version control, and we have 3 different branches.  “dev” which is the main development branch.  This is where I commit all the changes I am currently working on.  “test” contains the code on the test server.  This is where my boss/co-workers test all new features/fixes.  “prod” is the main production server where the main app is running.

After committing code into “dev” and testing it on the dev server that I was working on, I merge the revision(s) with the “test” branch.  I use a program called TortoiseSVN.  I just right-click on the folder containing the checked-out “test” branch, and select “merge”.  From there I can pick the revision(s) I want.  Then I commit them.

On the test server (via SSH), there is a script that I run that will copy the code from the SVN into the webroot.  From there, it sends out an email to notify our team that there are new changes to test out.

The production server works exactly the same way.  Merge, commit, then run deploy script.  It’s fairly automated, and I don’t really see how it could be anymore automated.  Having to manually merge/commit might be annoying, but it’s the safest way.  It makes sure you only run the commits you want.  It makes sure that you know *exactly* what code is being moved into each server.

It’s a process I’ve gotten used to, so it’s easy and quick for me to do it.

-Eric aka ens3261

Improving the software development process

There are many ways to portray the software development process and its life cycle.

I won’t use the conventional names for the steps and just proceed to explain them due to the differences in the names and number of steps/phases between the different existing methodologies. Basically, we tend to have 5:

Phase 1:
Gather information and state what is needed.

Phase 2:
Design the software and document it.

Phase 3:
Code the desired functionalities.

Phase 4:
Look for errors and resolve them.

Phase 5:
Deploy the software and give technical support.

These are the 5 basic phases which sometimes are subdivided, which creates more phases.
In my experience in the IT development area, there has always been a weak point which many projects don’t put the enough attention. This weak point is the first phase.

Imagine a house, you have the planes and you start building it.

After the first 2 months you realize many things:

– The ground ins’t as stable as you thought it would be.
– You didn’t consider enough space for the drainage
– You will need one more column because the second floor seems a bit unstable.
– You will need much more construction material than expected.
– You will need 6 more months than expected due to all the changes that will take place.
– Your budget is limited and you can only extend the building project 3 months.

Why did this happen? It wasn’t planned thoughtfully enough. This is what happen on many software projects which don’t give the enough importance to the first phase, then they have to invest more resources and rush in order to get it done as soon as possible. The software ends up patched as the house example with many extra columns to support it. At the end the company invests more resources to have a less quality product because they wanted to start sooner the “real work”. This is a common mistake that can be easily avoided by giving extra time to the first phase. After it is completed, start it over again in order to find holes on it and fix the requirements because it is easier and faster to do it in the planning phase than doing it in the next phases.

An example random project budget in resources (time/money):

Phase 1:
$3
Phase 2:
$5
Phase 3:
$9
Phase 4:
$4
Phase 5:
$2

Planned Total: $23

When you are in the 4th phase, you realize there was a big mistake which with only $1 more on the first phase, but since you are alredy in the 4th phase, that cost will be multiplied:

Extra needed now:
Phase 1:
$1
Phase 2:
$2
Phase 3:
$4
Phase 4:
$4

Extra total: $11
New Total: $34

The cost of the project increased a 48% based on the initial cost.

This just an example to show what could happen if something important is forgotten or not taken into account in a software development project. The 48% might look like an exaggeration but I have seen it directly, and it was more than a 48% extra investment which was needed in order to finish the project due to the initial error of overestimating the initial phase.