RE: Being an expert

[Karen Casemier <karen -dot- casemier -at- provia -dot- com>]

OK, my vote is for the technical vs. non-technical writer thread as the
longest ever on Techwr-l.

Here are my two cents -- I'm adding them because I think there is a
misunderstanding about how "expert" information can be used. I'm speaking
about software writing, because that is what I'm familiar with. And I'll
start out by saying I do not read code (not well, at least), but it is the
next thing I plan on learning.

If I am documenting a software product for a typical end-user, that end-user
doesn't not care how the product is coded, they only care how to do their
job. They care about the front end, not the back end. Even if I had access
and understood the code, I certainly wouldn't be adding that information to
a typical user manual. The main thing I need to do is become a power-user of
the program (which in itself is something many tech writers fail to do).

HOWEVER, understanding the code could make my job easier. Basically, it
removes a major dependency on the developers to explain certain types of
information. The code could help me differentiate between a poor design (the
function is working as designed, even if I don't agree with the design
itself) and an actual error (bug) in the program. The code can also list
valid values for specific fields (as just one other example). There is a lot
of information I could find in the code that would help me understand how
and why the program works the way it does on the front end. (Which is why I
want to learn how to do it).

I recently got on the internet, took some free tutorials, and got an SQL for
Dummies book so I could navigate more comfortably in SQL. This cost me no
money - I was able to borrow the book from a developer and got tons of good
information for free on the internet. In SQL I can view all the tables in
the database used by our program. Do I use this information directly in my
user manuals? No (that info does belong in a DB Administrator guide, but I
understand that not all writers are responsible for this type of
documentation). But by viewing information in this format, I can identify
relationships between the tables, which in turn helps identify prerequisites
for certain tasks in the software. I can manually add records that would
normally be downloaded from a host system so I can actually work through the
front end of the program in the same way that a user would. Again, just a
few examples - there are many more ways I use this information. And I don't
have to be constantly trying to get someone from Development to help me with
this.

Could I write the manual without the SQL knowledge? Yes - but I can write
*more accurate and complete manuals* with it, without depending on another
department (and I think most of you will agree that removing those annoying
dependencies makes our job easier). I look forward to adding another layer
when I can start getting into the code.

Karen R. Casemier


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Want to support TECHWR-L? Get shirts, bags, hats, clocks,
and more from the TECHWR-L Store. All proceeds support TECHWR-L. 
http://www.cafepress.com/cp/store/store.aspx?storeid=techwhirl

Save up to 50% with RoboHelp Deluxe. Get 2 great products for 1 low price!
You'll get RoboHelp Office PLUS RoboDemo, the software demonstration tool
that everyone's been talking about. Check it out and save!
http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com 
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com 
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.