Tech writing tie-in (was - Re: Can an AI bot write technical documents?)

[Jan Cohen <najnehoc -at- yahoo -dot- com>]

You did better than I did.  All I got when I visited the personalityforge.com link you mentioned below was:

MySQL Error: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near '' at line 3 in /Library/Webserver/AIEngine/engine.php on line 29

Query:   SELECT IsOn,UserName,MakerID,Serialxnone,Compound,GossipLevel,MemoryLevel,FlashActive,AIScript,Development  FROM Users  WHERE UserID=

which leads me to a (believe it or not) technical documentation tie-in.  Note how  the server erroneously informs me, as the client, that I'm somehow associated with the source of the SQL syntax error.   In fact, the error was generated by a series of unexpected events, which I'll get to next.  

In a properly set-up site, what I should have received was a message letting me know that I needed to sign into this site to use this particular AI functionality.  But because the site isn't properly set up to deal with someone circumventing the sign in process like I did (because I clicked on a link I wouldn't normally have had access to unless I was signed in), the server rightfully acknowledges that something happened to my userID, which it would have had access to had I signed in.  So it makes its best guess (which is designed into the MySQL binary), assumes the php script somehow caused the loss of the userID, and tells *me* to RTFM.   

Now I'm guessing here, but what's probably missing from the process in this case is what's known in the "hidden" html world as a "referrer."  A referrer lets a server know what path you took to get to a particular internet address, and is usually some semblage of the url you were at just before arriving (fully qualified or not).  In this case and by way of the link in Lauren's message, my referrer would have been something like http://www.yahoo.com/xxxx...n.  Had the server's sign in process been set up properly, it would have recognized that my request to access the AI tool originated off-site, and would have told me to sign in prior to using the AI tool.  Had those instructions been proffered and followed (again, if I surmize correctly), I would have been assigned a userID.  

Which leads me to the technical documentation tie-in.  The site in question relies on a number of relatively complex technologies, all of which are interlinked.  Above and beyond its html and CSS, there's javascript, php and MySQL, each of which has (in a sense) its own user manual.  But if you turn to the MySQL Server user manual the error message mentions above, you probably won't find much in the way of telling you to ensure that, e.g., clients sign in and get a userID before proceeding further.  Instead, what you get is the weak link in the chain, a breakdown in the process, and a confused client.  

Fortunately, there are writers who understand these types of issues, those who recognize that today's web sites are often made up of a set of integrated applications.  They develop their documentation with this in mind, and either incorporate the integration aspects of the entire process into their documentation, or make note of the need for integration where required, and refer the reader to other documentation.  In the case of the personalityforge AI site, it's possible that the documentation for the various versions of MySQL Server were written with a strong (and perhaps sole) focus on the MySQL Server application itself.  It is, after all, an opensource application, designed by software developers, perhaps written by writers who were told what to write.  But it could also be a case of "no time to read <vbg>), and even if there are some aspects of the required integration steps in these MySQL documents (again, if this is the case), the folks who put together the
 personalityforge AI site might have overlooked them.

I guess what I'm trying to get at here is the notion that technical writers often find themselves developing documentation for equipment or software that makes up a smaller set of the whole.  And in such cases, where integration plays an important role, the big picture counts.  Especially if the sum is made up of a lot of smaller puzzle pieces that will only fit together properly in a certain way.

jan cohen


Lauren <lt34 -at- csus -dot- edu> wrote in part:
Bildgesmythe took attitude with me when I asked if it could write technical documents.  "The bot no longer wants to talk to you."  You know it's sad when you bots blow you off.  http://www.personalityforge.com/directchat.php

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.