How useful are most glossaries in Technical Manuals?
I’ve got a manual here on Open Directory Administration. It’s not the simplest thing in the world to do: you’d expect someone implementing any sort of LDAP or domain to be a relatively experienced system admin. As a techie who’s never administered a domain before, there’s a fair amount of learning curve for me (especially when you consider that what I’m actually trying to do is extend my university’s Novell eDirectory for a suite of macs that will benefit from the extra management capabilities of OS X Server).
So I think it’s kind of funny when the glossary is full of terms like:
- FTP File Transfer Protocol…
- Administrator A user with server or directory domain administration privileges…
- group A collection of users…
- IP Address …!
You might not expect the man on the street to know what those sorts of terms mean, but the idea of someone expecting to be able to set up directory services not knowing them is… well, silly at best and scary at worst. Plus, the definition for ‘administrator’ relies on the use of the noun administration: in other words, it’s recursion rather than definition.
I had to lose four pages for the thermal binding machine to cope with the manual. I don’t think I’ll miss the glossary.