Jump to content

Writing Documentation for a solution.


This topic is 6890 days old. Please don't post here. Open a new topic instead.

Recommended Posts

I'm beginning to write a users guide to a solution that I created but I'm looking for some help. I've read that the terminology I use should be easy for none FileMaker developers to understand.

I am stumbling over what to call buttons that will switch a user between tables and ones that switch them to a different layouts like a (list view or a table view) of the same table. Also sometimes I have buttons to show different related data in portals. (Portals there

Link to comment
Share on other sites

In all cases of doubt, consult with the users of the system!

Most users they don't know (or care) about the difference between switching between tables and layouts. Nor should they. But they do need to know whether they are switching between, say, invoices and clients (which is a major functional difference to the user) but they may not be so concerned about switching between a list layout and a form layout of the same data (which is of little functional difference to the user).

"Has anyone else given this much thought?"

Yes, as a matter of fact they have.

http://www.joelonsoftware.com/

http://www.useit.com/alertbox/

http://www.jnd.org/

http://www.asktog.com/

http://www.sylvantech.com/~talin/projects/ui_design.html

http://www.shorewalker.com/section1/webui.html

Welcome to the tip of the iceberg, the thin end of the wedge. wink.gif

Link to comment
Share on other sites

Disclaimer: This is my personal opinion, which may not mean much, as I don't know what the solution actually is, nor whether other business terms would better apply.

Most of the terms that describe FileMaker objects are also regular words, being used in much the same context. This is one of the primary reasons FileMaker is easy to use; objects were named deliberately. Words like "portal", "layout" and "records" mean generally the same thing outside of FileMaker as inside. So, if there are not better words available I see nothing wrong with them. Perhaps you could add a small glossary at the introduction, to give people the idea.

The concept of "table" is not so easy. But every organizational scheme needs some words for its objects. "Table" may be a little geeky (common though, being used in most databases), but this could be an advantage, in that you don't confuse it with other more specific business objects.

I don't see anything especially wrong about people who are using FileMaker learning a few FileMaker terms. In the long run it is a good thing. I guess the hard part is integrating the business terms of the particular business with the FileMaker terms of the database. That is a black art for sure B)-] But, if done well, they'll both be able to use the solution, and have a better concept of how it works.

Conversely, if you avoid all use of FileMaker terms, you're going to have to come up with something, and I doubt you can come up with better; it will have to be very consistent.

Another thing I learned, while writing documentation myself, is that if you find yourself tediously explaining what seems more and more like a funky work-around, it usually is. It's actually a good way to find places where your solution needs better interface programing. Best to stop writing excuses and go make it work like it should :-/

Link to comment
Share on other sites

There is no substitute for watching how the users go about their job... nobody knows how they use the database better than them, as opposed to how the developer *designed* the database to work. The database should always fit the user model. (You've got to read Don Norman's book "The Design of Everyday Objects" it goes into the different mental models, and it's illuminating stuff.)

I'm building a new system, and the old system is still in production. One user was complaining of odd behaviour in the old system so I went to check it out. They demonstrated the problem while entering a few records for me, and I noticed that they used the keyboard shortcut Ctrl+"-" to insert the current date into a field. It was quick and efficient and almost a reflex response because they use it so often. It'd be a feature that would be sorely missed in the new system, it's absence would significantly slow them down.

So I immediately went back and made sure that the shortcut works in the new system, because I have menus set to editing only and it may block that command. If it didn't work I'd have no choice but to come up with some work-around for the shortcut. (As it turned out, the shortcut does work even with the menus dispabled. Phew.)

You've got to have no emotional attachment to the interface (or any part of the development) and you've got to learn from the users.

This does not mean that the users have all the answers: they don't. The developers job (my job) is to come up with new ways to design the system to make the processes more efficient. But ultimately it's the users that decide whether the idea is good or bad.

I'm doing some simple benchmarking this afternoon: timing how long it takes to enter some new widgets into the old system, compared to entering the same widgets into the new system. If the new system is slower then it's not much of an improvement, from the user's perspective.

Link to comment
Share on other sites

Thanks for the comments. I'm starting to think I over thinking which is complicating things a bit. This is my first full solution (besides a stripped down demo) and I just want it to be useful if someone wants to download it and buy it.

Its not a customized solution for one company but more like a "canned" product. I am also going to follow your advice Fenton and just include the Filemaker terminology. So if my product is a flop I have someone besides myself to blame. (just kidding)

Again thanks the the input.

Link to comment
Share on other sites

Well, if you are writing a user guide, you really have to know who your target users are. This is also important for your marketing decisions.

Business Executives with MBAs but limited IT skills

Teenagers who grew up with PS2 and iPods

Bored Househusbands

Factory workers to whom English is a second language.

Link to comment
Share on other sites

The solution is for IT Depeartments so my target users are IT people so they will have some knowledge but I try to never assume anything. You know what they say about assuming.

grumbachr

Link to comment
Share on other sites

This topic is 6890 days old. Please don't post here. Open a new topic instead.

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...

Important Information

By using this site, you agree to our Terms of Use.