I've written a simple, business application which generates a report from information in a database. The only user input required are two file paths--one to a list of items to report on and another to write the report to--and a slider that picks how far back in time to look.

The paths are displayed in text boxes which you can edit/paste into or use a browser in the file menu to change.

The most difficult part is the input file. It's a plain text file with a particular delimiter requirement. If a user has even a bit of computer literacy, this will likely be the part that requires the most help.

The Question

How should I organize this small amount of information on a help form? I don't have closely enough related data to justify the typical Windows help tree, a scrollable list would be somewhat long and hard to navigate, tabs seem strange for this use, and I'm not really aware of another way to break up the data.

Do you have any suggestions on how to present this amount of loosely connected info? As a note, more in depth external help is also something I've created, but there needs to be an internal help system as well.

Edit: There seems to be a lack of clarity on my end. I am seeking a way to layout a medium amount of help information so that it is most usable. A tree structure is not appropriate as there are not clear parent-child relationships between topics. The only other layouts I can think of are tabs and a list. Neither of these seem right to me, so I'm seeking another opinion on how this information can be presented.

  • How about contextual popup help that shows in a modal window over the form when a link is clicked? Sep 19, 2011 at 21:45
  • That's a pretty good idea. While that would work well for labeled components, I don't really see how that would work for things like the input file. I'm also a bit worried about surprising users with a modal window that may open unexpectedly. Sep 20, 2011 at 0:38

3 Answers 3


Does your plain-text file provide for comments? (That is, can it include lines that will not be read by your software?) If so, comments right there in a sample or starter data file explaining and showing the format would help users get going. The first time they use your application they'll copy and edit that sample file; after that they'll probably copy their own past files (or will have internalized the format, depending on how complex it is).

Edit based on question edit: For providing the help page (that could point to or duplicate the doc in the starter file), for a medium amount of information you might consider a column of "section" links on a single page, like in our FAQ.

  • This is a great idea about how to improve the textual input and I'll implement it tomorrow. Unfortunately, it doesn't actually answer what I asked; what is the most effective way to present a small collection of help documentation? Sep 20, 2011 at 0:33
  • If what you are documenting is the input format and you make it so it's "self-documenting", what is left for the help page? Or are you asking how to organize the information that you're going to present, regardless of whether it's a form or comments in the input file? Sep 20, 2011 at 12:53
  • I think that one should provide redundent help. That way, if a user doesn't find one, they will still have a chance to find others. I'm asking what the best way to display a medium amount of, only slightly related, information is. Sep 20, 2011 at 15:05
  • This is a really good idea. I love it when documentation can accompany the actual stuff people work with, but not get in the way. Sep 20, 2011 at 20:22

In the case you describe, I would add a "readme" HTML file with the help information and provide a Help button on the form that would open this file in the user's standard browser.

The help file can include a sample input file with comments and explanations on the format to be used, like @Monica suggested in her answer.

If you do not want to distribute more than the exe, the HTML file could be included in the exe as a resource and extracted when the help button is clicked the first time or whenever the HTML file is not found in the expected location. (And don't make the expected location the same folder as the one where the exe lives if that is under UAC control on Windows).


Well my internship is over and the final version published! Despite what my initial concerns were in the question, the best way to display this information is to use a left hand list with a scrollable, variable text area on the right based on their list selection. This keeps closest to the windows convention of using a tree in the list's place but is better in this case since the information is in a non-hierarchical form.

A typical user will likely not even notice the subtle difference, which keeps with the principle of least astonishment.

All of this was put in a modal window which featured a close button for users who couldn't find the X up top.

  • The way you tell your design or design principles is not something easily understandable with just words. I'd kindly recommend sharing any visuals if applicable. Mar 4, 2018 at 14:22

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.