IMO, all tech writers should know the basics of relational database design. Colleges should incorporate it into tech writing programs. I’m convinced of it. Why? I had worked for many years as a tech writer before taking a database design class, and have continued to work in that capacity for a number of years (and still counting) afterwards. It makes such a difference that I put it right up there as one of the basics that all tech writers should know.
After taking the class, I was able to make UI usability suggestions (a column in a table didn’t need to be on the screen; I realized that because I knew how tables work in databases). I was also able to decipher some error messages during dev because I was familiar with database lingo. Granted, I’m no DBA, but my limited database knowledge made a difference. Portions of the specs were also more clear. Most of all, though, I could see how understanding of database design and operation made a critical difference in setting up docs.
Planning docs from a database design viewpoint definitely adds another layer of complexity and time. However, it’s worthwhile. Your docs will be easier to maintain and share.
Databases, of course, have tables. The tables have rows of records. The database also has normalization requirements to ensure that data is broken down to its lowest common denominator. You don’t want redundancy; you don’t want to enter or update information twice.
For example, if you have a tag in your XML called “Name” and it includes first and last name, it could be trouble. If you have a database table for names and a separate record for first and last name (not one that includes both), the XML data won’t import well into the database. It’s better to have two XML tags. For instance, something like individual “FirstName” and “LastName” tags within a “Name” tag would work well. Then, the database table could be called “Name” and have two records: FirstName and LastName. The data would transfer back and forth between XML file and database without much difficulty.
To go one step further, let’s say that you have a database table with FirstName and LastName records. It’s also a good idea to have the XML file use the exact same name. If you use “First” and “Last” in your XML file and the database has FirstName and LastName, then you could have trouble. Match them up! Make your life easier.
These are some very basic examples of considering database design when setting up XML and XSL files. By knowing how databases work, you can name and arrange your XML tags in such a way as to facilitate import and export to a database. After all, the content in an XML file is data. Once you get that XML into a database, you can access it in varied ways. This includes web pages, reports and portals. That, however, is another story for another day.