I'm implementing a help system for a desktop app (Win32) and am looking for how to go about designing it.
What kind of structure should a help system have, what's actually helpful for the user?
e.g. Should the help system be a big list of FAQ's (office 2010 help seems to be like this)? or should it be a Feature list documenting and describing what everything does (This is probably only helpful if the user is not sure how a feature they already know about works)
What kind of knowledge should I expect the end-user to have? It's probably slightly demeaning to write into the help file that File -> Open Project Closes the current project (if present) and Opens an existing project.
What I'm looking for here is some guidence, a set of features any good help system should have and a method of organising the topics in a way that users can find them.
"Open project" can also be a good place to put a reference to the definition of a project, and other more general descriptions and procedures relating to opening of projects.
In general CHM help is accessed either via context sensitive help (which is the typical for the file->open case) and via the general table of contents, fulltext search and indexes. Most recent apps seem to only create one help page per container (a dialogue, or pullodwn menu), where they list all the items on that screen (e.g. by annotated screenshot) and not a lemma for each item (checkbox, menu entry) in the GUI. Less clutter and navigation, and many points only need a fairly short description
Besides context sensitive help, one can also browse the help via the help system.
A CHM is pretty much a bit like an e-book, with a table of contents (TOC), index and optionally support for fulltext search.
The index and fulltext search are ways for the user to search for content.
The main difference is that the index is more under your control, and the fulltext search is largely automatic when enabled.
The TOC is a treeview of nodes that act like the TOC in a book, and should fixate the general structure of the "ebook". FAQs are typically an appendix in this TOC.
Besides this, there is a default "entry" page, which is like the homepage of a website. It should navigate users to the most commonly searched topics.
Be careful by comparing to Microsoft products. They sometimes use systems that are not available for end-users/developers yet.
Good help uses all these elements.
There are broadly two styles of help: reference-based (i.e. what does this checkbox mean?) and task-based (how do I achieve XYZ?).
You're probably best off creating a task-based tutorial first, backed up by a FAQ if necessary.
Related
Hello Stack Overflow Community!
I am making a directory of many thousand custom mods for a game using HTML tables. When I started this project, I thought one HTML page would be slow, but adequate for the ~4k files I was expecting. As I progressed, I realized there are tens of thousands of files I need to have in these tables, and let the user search though to find what they are missing to load up a new scenario. Each entry has about 20 text entries and a small image (~3KB). I only need to be able to search through one column.
I'm thinking of dividing the tables across several pages on my website to help loading speeds and improve overall organization. But then a user would have to navigate to each page, and perform a search there. This could take a while and be very cumbersome.
I'm not great at website programming. Can someone advise a way to allow the user to search through several web pages and tables from one location? Ideally this would jump to the location in the table on the new webpage, or maybe highlight the entry like the browser's search function does.
You can see my current setup here : https://www.loco-dat-directory.site/
Hopefully someone can point me in the right direction, as I'm quite confused now :-)
This would be my steps,
Copy all my info into an excel spredsheet, then convert that to json, then make that an array for javascript (myarray), then can make an input field, and on click an if statement if input == myarray[0].propertyName
if you want something more than an exact match, you'd need https://lodash.com/
in your project.
Hacky Solution
There is a browser tool, called TableCapture, to capture data from html tables and load into excel/spreadsheets - where you are basically deferring to spreadsheet software to manage the searching.
You would have to see if:
This type of tool would solve your problem - maybe you can pull each HTML page's contents manually, then merge these pages into a document with multiple "sheets", and then let people download the "spreadsheet" from your website.
If you do not take on the labor above and just tell other people to do it, then you'd have to see if you can teach the people how to perform the search and do this method on their own. eg. "download this plugin, use it on these pages, search"
Why your question is difficult to answer
The reason why it will be hard for people to answer you in stackoverflow.com (usually code solutions) is that you need a more complicated solution (in my opinion) than hard coded tables and html/css/javascript.
This type of situation is exactly why people use databases and APIs to accept requests ("term": "something") for information and deliver responses ( "results": [...] ).
Thank you everyone for your great advice. I wasn't aware most of these potential solutions existed, and it was good to see how other people were tackling problems of similar scope.
I've decided to go with DataTables for their built-in sorting and filtering : https://datatables.net/
I'm also going to use a javascript array with an input field on the main page to allow users to search for which pack their mod is in. This will lead them to separate pages on my site, each with a unique datatable for a mod pack. Separate pages will load up much quicker than one gigantic page trying to show everything.
I'm considering using mediawiki as my company's internal knowledge base and am trying to understand how to build out effective team sections. Unfortunately, I'm not finding much information on this.
Ideally we'd have a separate knowledge base sections for devs, product, design and HR; all in the same system with the ability to cross-link. Each of these sections would be able to have it's own landing page and we could search for content specifically within that section.
It looks like using categories might work, but initially this feels clunky and I'm not sure if it provides the level of hierarchy I'm looking for. I would love to get your ideas and any links to examples that have done this well.
Thank you!
If by segregation you mean limited visibility (ie. team members generally shouldn't be able to see other members' content), then MediaWiki is probably not the right choice for you as it does not have granular read access control.
If you are simply looking for content organization, namespaces provide an ugly but easy way of partitioning (almost everything supports filtering by namespace). Categories are more elegant but not so well integrated - you can filter search results by category but you can't do it for most other things like recent changes or user contributions.
I was wondering if anyone knew of an application that would take a GEDCOM genealogy file and convert it to HTML format for viewing and publishing on the web. I'd like to have separate html files for each individual and perhaps additional files for other content as well. I know there are some tools out there but I was wondering if anyone used any tools and could advise on this. I'm not sure what format to look for such applications. They could be Python or php files that one can edit, or even JavaScript (maybe) or just executable files.
The next issue might be appropriate for a topic in itself. Export of GEDCOM to RDF. My interest here would be to align the information with specific vocabularies, such as BIO or REL which both are extended from FOAF.
Thanks,
Bruce
Like Rob Kam said, Ged2Html was the most popular such program for a long time.
GRAMPS can also create static HTML sites and has the advantage of being free software and having a native XML format which you could easily modify to fit your needs.
Several years ago, I created a simple Java program to turn gedcom into xml. I then used xslt to generate html and rdf. The html I generate is pretty rudimentary, so it would probably be better to look elsewhere for that, but the rdf might be useful to you:
http://jay.askren.net/Projects/SemWeb/
There are a number of these. All listed at http://www.cyndislist.com/gedcom/gedcom-to-web-page-conversion/
Ged2html used to be the most popular and most versatile, but is now no longer being developed. It's an executable, with output customisable through its own scripting syntax.
Family Historian http://www.family-historian.co.uk will create exactly what you are looking for, eg one file per person using the built in Web Site creator. As will a couple of the other Major genealogy packages. I have not seen anything for the RDF part of your question.
I have since tried to produce a Genealogy application using Semantic MediaWiki - MediaWiki, the software behind Wikipedia, and Semantic MediaWiki includes various extensions related to the Semantic Web. I thought it is very easy to use with the forms and the ability to upload a GEDCOM but some feedback from people into genealogy said that it appeared too technical and didn't seem to offer anything new.
So, now the issue is whether to stay with MediaWiki and make it more user friendly or create an entirely new application that allows for adding and updating data in a triple store as well as displaying. I'm not sure how to generate a family tree graphical view of the data, like on sites like ancestry.com, where one can click on a box to see details about the person and update that info or one could click on a right or left arrow around a box to navigate the tree. The data comes from SPARQL queries sent to the data set/triple store both when displaying the initial view and when navigating the tree, where an Ajax call is needed to get more data.
Bruce
I develop an online, Flash-based multiplayer game. It is a complex game, and requires a lot of documentation to fully explain it to our users. Ideally, I would like to find MySQL-based wiki software that can provide these editable documentation pages outside of Flash (in the HTML realm) but also within Flash for convenience, and so that players can refer to the information without interrupting their game or having to switch back-and-forth between browser tabs. I am expecting that I would need to do a lot of the work on the Flash side myself, as far as formatting, for example, but I would like to feel comfortable in querying the wiki's database to get info directly. I guess this means that I need a wiki that is structured relatively "flat" or intuitively so that I can do things like:
Run a MySQL query that returns a list of all the articles (their titles and IDs) in the wiki
For each article ID in the wiki, return the associated content
This may mean that I have to limit the kinds of formatting I put into the wiki -- things like tables would probably be omitted since they would be very difficult, if not impossible, for me to do on the Flash side. And that is fine!
Basically I am just looking for suggestions for wiki software that is pretty easy to use, but mostly is technically simple enough on the back-end that interfacing with it directly via MySQL is not difficult. When interfacing with the database directly, I only need to READ data. Any time the wiki would be edited or added to would be done via the wiki's actual front-end application.
Thanks for any suggestions!
MediaWiki is the best-known and best-supported MySQL-based Wiki, used for plenty of complex game documentation projects like MinecraftWiki. The database is not all that simple, but it's well documented and basic read operations aren't too hard. For example, here's how to fetch the current content of the page "MyPage":
SELECT old_text FROM page,revision,text WHERE page.page_title="MyPage" AND
page.page_id=revision.rev_page AND revision.rev_text_id=text.old_id;
(And yes, old_text is the current content of the page. Don't ask me why!)
Your main problem will be figuring out how to parse MediaWiki markup, there are plenty of parsers for it but I'm not aware of anything that would work in Flash.
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.