Revised 2015/08/04
“The job isn’t over until the paperwork is done.” That’s still true even in a paperless age. One really should document one’s work, but that’s usually something that gets put off until the last minute and often ends up being neglected altogether.
Furthermore, it’s notoriously true that software engineers who are perfectly comfortable speaking techie talk to each other might as well be using Swahili when it comes to communicating with end users, which is why there are career opportunities for tech writers who are able to translate between Geekspeak and English.
But nobody’s better at describing to you what you need to know than you yourself. This is particularly true of the rarer activities, such as an annual fund-raising drive or a seasonal performance, where you’ve had plenty of time to forget how you did it the previous go-round. Wouldn’t it be nice if you could easily call up your former self to help you out this year?
Well, we’re working on the next-best thing, which is a wiki. It’s defined on the most famous one of all, Wikipedia, as a tool “which allows people to add, modify, or delete content in collaboration with others. [Typically] the content is created without any defined owner or leader, and wikis have little implicit structure, allowing structure to emerge according to the needs of the users. ... ‘Wiki’ is a Hawaiian word meaning ‘fast’ or ‘quick’.”
That’s certainly true of the ones I’ve begun installing in the one place where you really need a friend, namely right in the database itself, so you don’t have to go rummaging thru your file cabinets or e-mail archives looking for your documentation. Also, and perhaps more importantly, having the wiki right under your fingertips when you’re solving problems makes it easier to document your processes, timelines, “whom to notify”s, etc. as you go along, rather than waiting till the end, when some of your knowledge will already have started to fade.
My wikis are about as super-simple as they can get. I give you a scrollable free-form text field into which you can type anything you want. I make it accessible, point you to it, and walk away. That’s it. The rest is up to you.
My wikis come in 2 basic flavors: file-level and table-level. The file-level wiki will be available on the Router screen, where it’ll appear on the “Documentation” tab, like this:
It will typically share that tab with the file’s E-R (entity-relationship) diagram, if it has one. Here's where you'll enter info about the file as a whole, or about aspects of it that involve multiple tables within the file.
You'll be able to get to a table-level wiki for any given table by means of a "Wiki" button located on that table's data-entry screen, normally right next to the "Router`" button:
An ordinary table-level wiki will initially open up as a floating window near the upper left corner of your screen, like this:
A "floating window" is one that stays on top of your regular windows, so your wiki window will remain visible and attention-getting until you choose to close it. But, if it's covering up something you need to see, just reposition it:
And, altho each wiki is associated with a given table, you aren't stuck having to look at that table while you work with the wiki. You can jump to some other table instead underneath it:
And you can open the wiki from that table as well and have 2 of them floating there simultaneously, allowing you to copy and paste back and forth between them:
Finally, while each wiki opens in a fairly discreet, petite little window, you can resize it to get a better look at what it contains:
Wikis are provided to you as a service to aid in your documentation. Use them or not, as you see fit. If you find that your wiki entries are starting to run on at some length, give some thot to putting an index at the top which would refer to subject headings further down.
Each record in each table also has a "Notes" field, into which you can jot down odd little bits of information about that particular record that don't fit into any of the standard fields. The "Wiki" field applies to the table as a whole, not to any single record within it; otherwise, you can use it in much the same way — for reminders and notes to yourself — if you wish. Generally, tho, it's intended for long-term "how to" writeups.
You know who’s the 2nd most likely (after you) to find your wiki entries useful? New employees. But in their case, by far the more valuable service will go in the opposite direction, not so much their learning from the wiki as their contributing to it! There’s no substitute for a fresh set of eyes using a system for the first time. They’re not handicapped by familiarity. They haven’t become accustomed to all the little inconveniences and inefficiencies that you’ve long ago adjusted to and take for granted. These are the very people who are in the best position to fill in gaps in your wiki that you overlooked because you thot they were “too obvious to write down”.
Take full advantage of the tremendous opportunity your new workers give you. Have them go right straight to the wiki to explain things that they had to figure out for themselves because your documentation was incomplete (or even erroneous).
The wiki is yours, not mine. I’ve got plenty of places where I can describe things from my perspective, including this blog that you’re reading right now, always accessible thru the “Entire Database System” button on the Router screen of your every file:
That same row of “info” buttons will also contain “This Particular File”, which gives you basic data on the file you’re in, following the same multi-page format in every file. It will also occasionally have a “Help” button for information that’s truly unique to that file.
As the above screenshot illustrates, I also make extensive use of pop-up tooltips to provide explanations of buttons and other features. Occasionally, when the explanation would be too long for you to read before the tooltip vanishes again, I give you a little purple “?” button that you can click on to go to a more detailed explanation.
Finally, there are some bits of information that are important to know but which you’re not likely to go looking for on your own. For those I give you always-visible text instructions, like this:
The point of running thru all of my forms of documentation is to emphasize that I am the geek here, and you are the subject expert. You don’t specialize in databases, and I don’t specialize in whatever work you do. What I have to say may not be readily understandable to you, or it may not address concerns that you have that I’m oblivious to. Thus the wiki. It’s yours. It’s a place where you can speak your language to yourself and your co-workers.
Enjoy the conversation.
Thank you for sharing such a kind and informative post,
ReplyDeleteFileMaker Pro 14 Video Training