Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
How do you implement user documentation in Access? I've never bothered with formal user documentation in the past; I tend to rely on good interface design to guide users (or so I tell myself). But I'd really like to know what people smarter than me are doing...
Here are things I think I would consider important (in order):
Simplicity: it needs to be simple enough that it can be updated easily as the code changes, otherwise the documentation will end up out of sync
Screen shots: a picture's worth a thousand words; screen shots must be easily integrated into the documentation
Integration: the user can get to the relevant part of the documentation with as little effort as possible; ie, pressing F1 on a form brings up help for that form vs. opening a help file and having to navigate a table of contents
Searchable: full-text search capabilities would be nice
Other considerations:
Online vs. local: local would be faster/more reliable, but online would be always available plus search engine indexable (allowing use of google site: searches and providing some SEO benefit as well)
User Editable: how much do you allow users to make changes to the documentation: full access (ie, wiki), no access, moderated forums, etc.
Version control: text-based formats are more conducive to versioning than say, an Access table with help text inside the mdb
Exportable to PDF: seems like a nice-to-have
In Access I've never created end user documentation. No wait, I did once about 12 years ago. And I paid someone to write the manual along with screen shots. I did also have the hlp files, etc, etc. But I don't recall the details now.
Now for the Auto FE Updater, where appropriate, I have a text control which is underlned and blue which the user can then click on. The code then opens up their web browser to the appropriate page on my website using the ShellExecute API Much simpler for me than trying to figure out some kind of help system that would work for both offline and online. I also update the ToolTip control to put in the exact URL so they can see where they are going to go if they click on the text control. That's a VB 6 program but close enough for your requirements.
You may find HTML Help suitable.
I don't produce documentation for my client projects unless the client pays me big $$$ for it, as it's extremely difficult. I often guide users in producing in-house materials that document procedures and standards, but in general, I design my apps for EASE OF USE.
That is in contrast to EASE OF LEARNING.
EASE OF USE and EASE OF LEARNING often conflict with each other, as a UI design that makes it really easy to perform a task the first time often gets in the way once the user is accustomed to how things work.
However, it's important to design the UI with two things in mind:
things that are done on a daily basis don't need to be easy to learn -- they need to be really fast and friendly for the person who already knows how to use the app. I have a 10+20 rule -- 10 minutes of training and 20 minutes of use and the user will never forget how to use it.
things that are done only very seldom should be designed with a UI that is transparent and easy and doesn't require the user to remember anything at all. These kinds of tasks are great candidates for wizard-style interfaces that step the user through the process and provide hints and tips as text along the way.
I also have a number of UI design conventions that I implement throughout an app. The example that springs to mind is that any subform that is a datasheet or continuous form has a doubleclick event that when activated opens a popup form with the full details for the selected record. Once users grasp this convention, they will assume that any subform is doubleclickable in order to navigate to the detail.
There are other such conventions, but that's the basic idea, i.e., to implement similar behaviors in similar contexts so that if a user learns to do something in one context, when she finds herself in a different place with a similar UI, the things learned in the original context are transferrable in terms of basic UI behavior.
You will need to do two things:
Create a help file with topic-ID's for all of the topics
Link this help file to your access database, and link the topics
We have had very good results with http://www.helpandmanual.com/. From one single source, you can create any sort of help file that you want: pdf, online, chm, hlp, xml, ... It has a screenshot tool integrated.
Every topic can have it's own ID and you can just link your access forms / controls to this ID.
I have done a very similar thing to Tony. Its kind of a user generated content type thing let me explain.
The database contains a table with a list of the form names and then the path of a help file (word doc) that corresponds with that form.
Certain users have access to a form that allows them to say what help file corresponds to each form
Each form then has a help button so when the user clicks on it they open up the correct help file.
This way it is totally flexible, if they just want one big help file then all the links point to that but if the users want to put the effort in then they can make a file for each one. As they help files are separate from the DB storage is not a problem and also help files can be changed without having to recompile the application.
You could merge this idea with Tony’s and have the help files online if you wanted. I just find this a nice design pattern
I recently stumbled upon TiddlyWiki and have been thinking about using that as a backend to the systems Kevin and Tony described.
Related
I recently discovered this very useful Netbeans tutorial for creating a simple JSF 2 CRUD application http://netbeans.org/kb/docs/web/jsf20-crud.html. The final product has somewhat limited usability as one is confronted with a myriad of web pages. I would like an example of how to consolidate the Create and Edit forms (using the same project if possible). This seems more in keeping with how a person would actually enter such information and would reduce the risk of data entry mistakes. Why enter a client and their billing address on separate screens? One should be able to add or remove addresses, if need be, on the client's edit form. Or if a new client has multiple addresses, enter them all on the client's create form. The application just seemed incomplete with no further tips on how to improve it. If one has knows of a useful book that covers this, then I would gladly read that as well. Thanks.
I didn't realize the complexity of my problem and found that I couldn't get what I needed using JSF2 with the information resources available. Through my searches, I also found that many others were asking about Master-Detail CRUD applications, which I then learned was what I needed, but in slightly different ways and not getting any solid examples. A problem properly stated is half solved and I didn't know the problem statement. Armed with more knowledge, I was shocked to find that the answers were not readily available outside of some videos on YouTube showcasing Oracle ADF. In the end, I was able to quickly build the application I desired using the Play! Framework. In a way, by not having my question answered I was able to find a solution that would prove to be a better fit for my needs; though I would have gladly bought a cookbook if someone had pointed one out.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 years ago.
Improve this question
I was wondering if there's anyway to layout what I want to code before I code it. Instead of drawing your ideas on a piece of paper, is there a program that lets you build a little demo or something before you start coding?
For mockups, I go with paper and pen or a cheap whiteboard substitute, but Balsamiq is an interesting tool for creating mockups. As it uses a deliberately handwritten style, you tend to focus more on the content than if the button should be 5 pixels to the left.
Here's an example:
(source: balsamiq.com)
Microsoft Visio is good for this kind of thing.
This is usually known as making mock-ups. There have been several questions that may be of help:
https://stackoverflow.com/questions/295589/what-program-should-i-use-to-mock-up-guis
https://stackoverflow.com/questions/54606/what-software-can-i-use-to-create-ui-mockups
etc.
Paper prototyping. There's lots of information at PaperPrototyping.com.
Honestly, you're wasting your time with enterprise tools, or charts and diagrams in most cases. Notepad will do. I learned it from a friend, which he likes to use the term "Notepad Architecture", and frankly I have had zero problems with designing applications, the underworkings, how things flow with one another. All you need is a good design, not necessarily pretty pictures.
For example, when I developed my user based system, I would do the following in notepad:
User (Role Based) System
- Administrators, Users
- Sql Server 2008
- Linq to Sql
User (Abstract Base)
- ID (GUID)
- Alias
- Username
- Password (Encrypted, MD5 Hash)
- First Name
- Last Name
- Email address
- Account Type
Administrator || User
Etcetera, etcetera. With the above as I type it, I already knew what and how it needed to be coded. What technologies were involved, and why they were involved. I didn't need any fancy drawing diagrams, or charts.
Ah, but what about complex events? Well, programming is like creative writing. Didn't you take a creative writing class before?
The user will start the program executable. The first form to be displayed is the sign-in form. When the form is shown, the user will be prompted to enter their credentials. The user will enter their credentials, and click "Sign In". The Sign-In service will then check the credentials against the database. If the credentials match, the form will close and display the shell, otherwise will display an error and allow the user to try again.
Now this is a small, but trivial and good example. Why on earth would I need a chart, flow chart, UML diagram, or other when all the logic and program flow is written elegantly (yes, feel free to critique) above? I know what needs to be written, again with what technologies, services, and how and what order to do it.
Trust me, notepad has been around for years! And there's a good reason for that, and why it hasn't changed any!
(It does take your mind a bit to get thinking a "creative writing" kind of way, but come on, you're a programmer! You do it everyday!
edit: See this post also.
For me, fireworks is the best tool to design user interface. There are lots of tutorials of how to use it.
For the UI, look at
Balsamiq or iRise.
If you want to model the behavior behind the UI, look at Enterprise Architect
You can try ForeUI, it is a tool for UI layout, interaction design and simulation.
There is nothing like good ol' paper and pencil. Also I recommend a book called Effective Prototyping for Software Makers. Here is a link!
You can try mind-mapping tools to put down your ideas in an organized way. Though it may not help you model your UI, it helps keep your thoughts organized. You can try Freemind. Its simple to learn and use.
Here's a sample from the Freemind wiki.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
After every new program written a lot of paper documentation remains.
Apart from the usual scribble notes from the programmers there usually is a nice heap of papers containing physical model explanations, calculations and so on (equations, tables, graphs, little pictures describing variables ...)
We usually do numerically intensive calculations in console applications, which are not released to the public (remain in the house, only results go out). Before each project is finished all those papers have to be packed somehow with the application, so that one day, when someone will be reusing parts of it, has some idea what is what in there.
So far, we've been using the 'dirty' solution of just scanning all of it, and packing it up on the disc with the application.
So I was wondering ... for all science guys here in a similar situation ... how do you handle project documentation which is needed, but not released to the public ?
(the one that does, goes to the dtp laddies, and they make it nice and shiny - not our problem anymore :)
I use one of three options:
Keep everything in my lab notebooks, which I archive myself, for low-level stuff
Scan the paper document, and add to source control in pdf. It's ugly, but if someone needs it, it's there
Transcribe the equations, results, etc... in a clean format (usually Latex) for future reference, and again, add to source control. Official paper copy gets signed (I work in a highly regulated domain) and filed in a binder.
In the projects I've worked on we have done a lot of physics calculations in our programs and consequently we have a lot of whiteboard sessions with equations we are working on.
We keep a wiki for each major project and after each whiteboard session we physically photograph the whiteboard with a digital camera and upload/organize it within the wiki. We also scan in paper documents from developers notebooks if it is important and include it in the wiki as well.
Then, we back up the wiki on disc for storage. So our solution is pretty similar to yours, other than we use the project wiki for organization.
If it's important, it seems to me you should treat the internal documentation with the same care with which you treat the public docs.
I create UI paper prototypes when designing the UI of an application, which produces lots of A3-sized papers (in one project we had many desks covered with papers). When the design is ready or it needs to be mailed to somebody, I take pictures of it with a digital camera, so that I can produce a series of pictures showing how to perform some tasks on the UI, which serves as documentation of how the application is meant to work. This serves also as a backup, in case somebody steals/cleans away the original papers.
Here is some of the thoughts... Not so practical though :)
We can make it part of our Check-in notes. This may help the developers going to maintain the application.
Update the requirement document/Low level design document with these items
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I'm not a usability specialist, and I really don't care to be one.
I just want a small set of rules of thumb that I can follow while coding my user interfaces so that my product has decent usability.
At first I thought that this question would be easy to answer "Use your common sense", but if it's so common among us developers we wouldn't, as a group, have a reputation for our horrible interfaces.
Any suggestions?
Source: http://stuffthathappens.com/blog/wp-content/uploads/2008/03/simplicity.png
Read Don't Make Me Think by Steve Krug. It is a great starting point, and an easy short read.
EDIT: This is mainly for web usability though, but it would still be a good read even if you are doing rich clients.
Just two things, really:
"A user interface is well-designed when the program behaves exactly how the user thought it would" - quoted from Joel Spolsky's User Interface Design For Programmers
Put your designs in front of a user. A real end-user is best, but for lightweight, rapid feedback, you can't beat hallway usability testing i.e. grab a co-worker.
If you remember Joel's advice and make sure you get feedback on whatever you do and act on it i.e. iterate, you'll not go too far wrong. And I would echo the recommendation for Steve Krug's Don't Make Me Think - it's probably the best work-related book I've read, bar none, and is just as applicable to desktop software as websites.
Hope this helps.
Don't make things work in a different way than your users are expecting (i.e. breaking the "back" button when using Ajax in web forms
Follow the K.I.S.S principal
Really, any rules someone posts will be a variation on the theme:
Don't Make Your Users Think
"Don't Make Me Think" has already been posted, see also
Design of Everyday Things and Designing with Web Standards which are also great for light usability reading.
Avoid modes. It's frustrating to a user when input works sometimes but not others, or does different things at different times.
The single most important piece of advice I'd give someone is to work on the UI first. Pen and paper and all. That way, you won't subconsciously couple buttons to functions, input fields to variables, etc.
The best UI might be a pain to code, and if your backend code is mostly written, it will sabotage your thinking.
Other than that, I'd point to Apple's Human Interface Guidelines. Of course, if your platform is not OS X, take the OS X sections with a lot of salt. What works in OS X might not work on Windows. You should embrace your platform's idioms.
OS X stuff aside, that document has some pretty good starting points on the fundamentals.
Here are some simple rules:
Fewer clicks are better.
Frequently used features should be easier to find.
Features for "advanced" users can be harder to find than the ones above.
Think about the number of mouse/keyboard clicks it takes a user to get to something.
PS - please don't tell the Microsoft Office 2008 people about this; the poor little guys would cry themselves to sleep tonight! :)
Think about the users that will use your app. Why are they using it and in which context?
Will the majority be pro users that know the domain in which the application is used and use the app a lot? Then don't be afraid of adding a lot of data to the screens as long as it arranged logically for users (normally that is not in alphabetical order :-). Think trade screens for stock borkers or airplane cockpits.
Are users occassional users? Keep it simple. Avoid context switches (keep all/as much as possible of necessary data for a task on the screen at each time). Don't break expectations of how gui widgets normally work. Design for failures.
Anything in between? Allow users to grow in the UI. Track usage so you can later determine where users seem to spend the most time so you can improve the most used areas of your app.
Test your app on friends and colleagues (the corridor test) to see if they are able to use it efficiently.
That's a start.
I suggest to read these blog posts from the Enso creators.
Of course they repeat guides/ideas/advices from books such as
The Design of Everyday Things and About Face, but nevertheless, the posts contain quite a few insights and (IMO) they are a good read.
What information does your user need, put that on the screen and nothing else. If you cannot define what the user needs - get another user.
Remember that your application will be one of many the user will have to deal with. Don't do things just to be different or kewl. Don't come up with unusual graphics, behaviors, terminology, or interactions. Use the standard OS controls, conventions, utilities, and behaviors.
Let your app interoperate with other apps; allow cutting and pasting of data, save your data in formats other apps can read, and allow importing data from other apps instead of using your UI.
If you are making a desktop app, do not try to take over the user's computer. Leave the user's Documents folder, task bar, and application preferences alone. Don't change anything already installed on the computer. Allow scripted or command-line interactions.
If you're making a web app, do not try to take over the browser. Do not try to subvert the standard menu bars, history, layout, or fonts. Allow the user to change the page using Javascript.
(1) Common actions should require as little effort as possible and should be obvious; on the other hand, actions that are rarely needed can be require a lot of steps and can be hidden behind menus and dialogs. To be able to do so, you should always describe what the user will want to do with the application by listing use cases.
(2) A UI should be selfdocumenting. The manual should be integrated in the application's dialogs and menu's, as users don't read separate manuals. For example, the keyboard shortcut should be shown in the menu item representing the action it is associated with.
Provide keyboard shortcuts for power users (even if it is as simple as "hit enter to search")
Don't put too much on screen at once.
If you pop up a messagebox, your users generally won't ever read it.
In addition to the other recommendations here, I'd recommend Designing Interfaces by Jenifer Tidwell as a good way of becoming familiar with UI conventions.
Also, The inmates are running the asylum By Alan Cooper is excellent for providing an insight into how to approach interaction design.
A good follow on to Don't Make Me Think is Robert Hoekman's Designing the Obvious. It's more focused on web applications, as opposed to web sites like in Krug's.
Simple is better than complex
Complex is better than complicated (eliminate 'nested ifs')
Intuitive (good elements needs no explanation)
Follow the convention (for example, underlined means link, red means error, tab goes to next field, etc.)
Use semantics to apply the logic (header reads first, paragraphs next)
whitespace is important
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
I've used a WordPress blog and a Screwturn Wiki (at two separate jobs) to store private, company-specific KB info, but I'm looking for something that was created to be a knowledge base. Specifically, I'd like to see:
Free/low cost
Simple method for users to subscribe to KB (or just sections) to get updates
Ability to do page versioning/audit changes
Limit access to certain pages for certain users
Very simple method of posting/editing articles
Very simple method of adding images to articles
Excellent (fast, accurate) searching abilities
Ability to rate and comment on articles
I liked using the Wordpress blog because it allowed me to use Live Writer to add/edit articles and images, but it didn't have page versioning (that I could see).
I like using Screwturn wiki because of it's ability to track article versions, and I like it's clean look, but some non-technical people balk at the input and editing.
I second Luke's answer.
I can Recommend Confluence and here is why:
I tested extensively many commercial and free Wiki based solutions. Not a single one is a winner on all accounts, including confluence. Let me try to make your quest a little shorter by summarizing what I have learned to be a pain and what is important:
WYSIWYG is a most have feature for the Enterprise. A wiki without it, skip it
Saying that, in reality, WYSIWYG doesn't work perfectly. It is more of a feature you must have to get the casual users not be afraid of the monster, and start using it. But you and anyone that wants to seriously create content, will very quickly get used to the wiki markup. it is faster and more reliable.
You need good permissions controls (who can see, edit etc' a page). confluence has good, but I have my complaints (to complicated to be put here)
You will want a good export feature. Most will give you a single page "PDF" export, but you need much more. For example, lets say you have an FAQ, you want to export the entire FAQ right? will that work?
Macros: you want a community creating macros. You asked for example about the ability to rate pages, here is a link to a Macro for Confluence that lets you do that
Structure: you want to be able to say that a page is a child of a different page, and be able to browse the data. The wikipedia model, of orphaned pages with no sturcture will not work in the Enterprise. (think FAQ, you want to have a hierarchy no?)
Ability to easily attache picture to be embedded in the body of the page/article. In confluence, you need to upload the image and then can embed it, it could be a little better (CTR+V) but I guess this is easy enough for 80% of the users.
At the end of the day, remember that a Wiki will be valuable to you the more flexible it is. It needs to be a "blank" canvas, and your imagination is then used to "build" the application. In Confluence, I found 3 different "best practices" on how to create a FAQ. That means I can implement MANY things.
Some examples (I use my Wiki for)
FAQ: any error, problem is logged. Used by PS and ENG. reduced internal support time dramatically
Track account status: I implemetned sophisticated "dashboard" that you can see at a glance which customer is at what state, the software version they have, who in the company 'owns" the custoemr etc'
Product: all documentation, installation instructions, the "what's new" etc
Technical documentation, DB structure and what the tables mean
HR: contact list, Document repository
My runner up (15 month ago) was free Deki_Wiki, time has passed, so I don't know if this would be still my runner up.
good luck!
I've also been investigating wiki software for use as a KB, but it is tricky to find something that is easy to use for non-technical people. There are many wikis that attempt to provide WYSIWYG editing, but most of the software I've found generates nasty inefficient html markup from the WYSIWYG editor.
One notable exception to this is Confluence which generates wiki syntax from a WYSIWYG editor. This still isn't perfect (show me a WYSIWYG editor that is) but is a pretty good compromise between retaining simple wiki syntax for those who like it and allowing non-technical users to contribute content. The only problem is that Confluence isn't free ($1,200 for 25 user license).
Edit: I also tried DekiWiki and while the UI is nice it doesn't seem to be quite ready for primetime (suffers terribly from the bad WYSIWYG output disease mentioned above). Also seems like they lack direction as there are so many different ways of accomplishing the same task.
Cerberus - it's more a full featured Help Desk/Issue Tracking system but it has a nice KB solution built in. It can be free but they do have a low cost pay version that is also very good.
Personally I use MediaWiki for this purpose. I've tried a number of other free and paid wikis (including Confluence) and have always been impressed with MediaWiki's simplicity and ease of use.
I have MediaWiki installed on a thumb drive (using XAMPP from PortableApps), which I use mostly as a personal knowledge base/code snippet repository. I can take it with me wherever I go, and view/edit it from any computer I'm using.
I think Drupal is a very possible choice. It has a lot of built-in support for book-type information capturing.
And there is a rich collection of user generated modules which you can use to enhance the features.
I think it has almost all the features you ask for out of the box.
Drupal CMS Benefits
We've been using a combination of
TWiki
OpenGrok for the codebase
usenet
LotusNotes based system
As long as there is a google search appliance pointed at these things I think it's ok to have any or many versions as long as people use them