Questions tagged [documentation]

text, usually about how to use a program.

Filter by
Sorted by
Tagged with
49 votes
6 answers
5k views

If nobody reads Privacy Policies or Terms and Conditions, why not change them?

Once I read that if you were to read all the Terms and Conditions, Privacy Policy and similar documents that you ideally need to read before using software or online services in a given year, you'd ...
edgarator's user avatar
  • 5,958
41 votes
9 answers
53k views

Documentation - do we "Click", "Push", "Press" or "Select" a button on a touch-screen interface

I'm writing some documentation for a web-based application that will run on Android tablets at the factory at which I am employed. I am having trouble wording the steps where the users must interact ...
eidsonator's user avatar
35 votes
5 answers
4k views

For a command to increase something, should instructions refer to the "+" key or the "=" key?

Our software uses the =/+ and -/_ keys for opposite tasks. For example, increasing or decreasing a value, or zooming in or out. No modifier keys are used. Here is the conundrum: If we refer to it as ...
Maxpm's user avatar
  • 453
35 votes
2 answers
9k views

Best practices for UI that introduces new users

I'm working on an onboarding UI to help new users get familiar with our platform and I was thinking about some good ways to implement it. From what I have come across so far, it seems that many ...
Ian's user avatar
  • 505
30 votes
9 answers
35k views

Should I use the name "Enter" or "Return" key?

I'm trying to list the what various keys do inside the documentation for my CLI program, but I'm not sure what to refer to this key as. It is commonly referred to as either Enter or Return, but which ...
ananaso's user avatar
  • 402
30 votes
8 answers
4k views

Should I use the terminology left/right click?

When instructing users which mouse button to click an element with, it seems standard practice to use the phrase 'left/right click': To download the file, 'right click' the link and choose 'Save ...
ajbeaven's user avatar
  • 403
25 votes
7 answers
13k views

Best way to display code to non-programmers

I'm asked to analyze the program responsible for printing our invoices. (Via SAP script) This program is pretty old and contains more than 4.000 lines of code. It sets a lot of different variables ...
Dennis's user avatar
  • 253
22 votes
8 answers
974 views

How can I make my UX work more "fun"? [closed]

I work as a User Experience Specialist at a relatively big company (400-500 employees), I sit here all day mostly cranking out big UX documents telling other people what they should do with their ...
Mashhoor's user avatar
  • 5,797
22 votes
4 answers
3k views

Enterprise UI standards

I'm in the process of creating a set of UI standards for a large enterprise, for multiple overlapping services (websites, mobile apps, internal systems and extranets). This is the first time I've ...
Chris Reynolds's user avatar
21 votes
6 answers
4k views

Does providing screenshots help with documentation manual?

I am documenting the site administrator and content creator roles for my web application which I am working on. The documentation manual walks the readers through how to add, delete, update members, ...
Traven's user avatar
  • 729
18 votes
5 answers
6k views

UX style guide techniques

I've recently started a major redesign for a large web-based financial tool. To aid future development, I'm planning on generating a UX style guide that outlines best practices for things like forms, ...
Sauce McBoss's user avatar
  • 2,158
18 votes
3 answers
40k views

example of a good software design document

Anyone got any online examples of good software design documents. I want personas, goals, scenarios and all that good stuff. I wish Cooper would have included a document with his books.
jrydberg's user avatar
  • 625
15 votes
3 answers
2k views

Normative ordering for modifier key combinations

When indicating valid key modifier combinations to users, is there a "correct" or normative order in which to describe them? For instance, if you wanted the user to press shift and control and alt and ...
Mishax's user avatar
  • 1,171
14 votes
6 answers
8k views

Which type of help system is best?

At my company we create Windows based desktop applications. In the past, we have created .chm files for our help documentation and have been happy with it. We have now been faced with some issues ...
Matt Rockwell's user avatar
13 votes
4 answers
409 views

Does UX apply to other documents, such as Word or Spreadsheets?

Does UX apply to documents such as a Word document, or a PowerPoint presentation? In other words, should the writer take into consideration the readers' experience of the document?
Möoz's user avatar
  • 1,639
12 votes
3 answers
697 views

Interactive 'page turn' documents - the case against using these?

What do people feel about interactive page turn documents? Here's an example (I'm not focusing on this report specifically - just happened to be an example I knew off the top of my head). Do these ...
Tom's user avatar
  • 511
12 votes
7 answers
9k views

Which one is better in our case if MDI is considered bad?

We are developing a financial reporting system, which is able to display many, I mean MANY, different reports from different angles. For example, the reports for position, deal, market risk, for ...
tete's user avatar
  • 223
12 votes
5 answers
4k views

Does using bold font for keywords and key points increase readability of user manuals?

I find myself writing quite a lot of articles, user manual-like documents, as well as posting hundreds of questions on stackexchange sites. Over time, I developed a certain style of writing, which ...
Alex Stone's user avatar
  • 1,617
11 votes
1 answer
631 views

Why do US food labels intermix desirable and undesirable properties without distinction?

I find it remarkable that the US FDA, after years of tweaking and no doubt lots of time and money invested, could only come up with a food label that is terribly confusing! The left side shows a ...
Michael Sorens's user avatar
10 votes
2 answers
790 views

Full lifecycle, version controlled, UX documentation - Is this possible?

I'm currently trying to implement a usable UX documentation system , streamlining the flow of work between User Researchers/Usability specialists, Information Architects and Visual Designers. Just to ...
user avatar
9 votes
4 answers
5k views

How to document user interviews

What are the best practices to document interviews with users - do you just document the conclusions and take aways or do you do a full transcript or both?
Tony Bolero's user avatar
  • 7,304
9 votes
2 answers
5k views

How do you source your persona photographs?

Like many of you I'm sure, I consider the creation of user personas to be a crucial part of the UCD process, particularly when starting a new project. While we all have our own techniques and styles ...
Chris Myhill's user avatar
8 votes
4 answers
472 views

Built in user guides

I want my web application to be self-explanatory. There are input fields and whole pages which need some paragraphs of explanation. How to integrate these user guides to my application? How to make ...
Witek's user avatar
  • 942
8 votes
2 answers
4k views

Industry standard for documenting IxD / UI Design Patterns?

What's the industry-standard way to document a design pattern? I have seen websites like ui-patterns.com and patternry.com that host and share design patterns, but when creating an reusing a design ...
Andy Fleming's user avatar
  • 1,712
8 votes
4 answers
3k views

how to implement a style guide for a team of 2-4

I am reading Lean UX right now, and there is an idea inside I have never read before. It is about style guide. I would like to implement that but with as small a foot print as possible for the ...
Kim Stacks's user avatar
8 votes
2 answers
798 views

What are some creative ways to 'document' UI error messages that are manageable and maintainable for developer handover?

Background I am a designer working for a large organisation that has thousands of system error codes that are associated with system default error messages. Sometimes these system default error ...
Andrew C. Duarte's user avatar
7 votes
4 answers
186 views

Building an archive of insights into our users

As UX Designers & Researchers we collect all this knowledge along the way, most of which is tied to specific projects. The crux though is that the insights can be highly relevant to later projects ...
Andreas Wolters's user avatar
7 votes
1 answer
2k views

What nomenclature do you use for UI Elements

Having worked with multiple OSs, platforms and UI Kits I always run into the problem of how to consistently naming things be that larger structures with names like Widgets, Views, Forms, Controls or ...
7 votes
1 answer
229 views

Quoting time and effort for UX research

Edit : I've added a little more detail to the main question here. There are many techniques and practices at our disposal to gain an understanding of the target audiences motivations and needs when ...
Adam Fellowes's user avatar
7 votes
1 answer
9k views

User Manual vs User Guide vs Documentation vs Quick Reference vs Handbook

I am aware this has already been asked at https://english.stackexchange.com/questions/59224/what-are-the-differences-between-manual-guide-and-instruction however from a user experience point of view, ...
dendini's user avatar
  • 1,523
6 votes
3 answers
208 views

When should you start working on help documentation on a large project?

I'm involved in a massive project that is turning 70+ antiquated systems into one system for a large company. The whole team and the executives at the company realize that this is a huge undertaking ...
maprules1000's user avatar
6 votes
4 answers
466 views

Should an API documentation include When-to-use and when-not-to-use list?

The target user base for the problem described below is one of the most neglected and underrated one - Programmers/Developers/Coders. Consider, for example, this java doc which is explaining about ...
gurvinder372's user avatar
  • 2,185
6 votes
3 answers
2k views

What is the usual way to specify a GUI?

What is the typical or most effective way to specify the design decisions and interaction patterns of a specific application's GUI? I began to realize I do not really know what the parts of a precise ...
Skip's user avatar
  • 261
6 votes
3 answers
763 views

Points to be kept in mind while writing a document to redesign a web application?

I want to redesign a website and write a document explaining my design approach and thought process. I have recreated the layout and explained my suggested changes. I have the content for the document ...
Ashin Mandal's user avatar
6 votes
4 answers
215 views

Documenting Rationale

I'm a UX architect working in house. In a nutshell wireframes are provided for our projects. We use JIRA as a way of tracking projects and confluence to document and archive them. Emails seem to be a ...
Antony J White's user avatar
5 votes
2 answers
3k views

"We" vs. "You" in documentation

I am writing a tutorial that describes a configuration of a linux server. It will be published on the internet. Quite often I want to write something like this: In this chapter we will configure ...
problemofficer - n.f. Monica's user avatar
5 votes
3 answers
233 views

Code reference site for developers

I'm looking for any UI / UX evidence for what makes a good code reference site. The information is a set of entries of classes (which contains properties and methods), subclasses, functions, and hooks ...
GaryJ's user avatar
  • 151
4 votes
2 answers
1k views

Which is more usable FAQ or Help documentation?

Which is more usable FAQ or Help documentation for web services? I need to provide contextual help content for each page within the service. Also same content will be re-used in websites. In my ...
jelumalai's user avatar
  • 1,327
4 votes
2 answers
141 views

How can end users training be integrated to the UX plans?

For many systems, performance can be significantly improved by educating the end users. It might even be argued that training is required to achieve optimal system performance: IIRC, Robert N. ...
Jørn E. Angeltveit's user avatar
4 votes
2 answers
881 views

Why are there not more interactive design / style guides out there? Aren't they more user friendly?

It seems like only the larger companies working on development and design frameworks are producing interactive documents that provide information about the visual and interactive design components/...
Michael Lai's user avatar
  • 26.8k
4 votes
3 answers
212 views

Allow uploaded Word documents or require markdown?

I have a site for writing tutoring that currently requires the student to copy and paste from Word into an HTML textarea, removing all formatting. We've thought about letting the student upload the ...
Caveatrob's user avatar
  • 141
4 votes
2 answers
149 views

What's the best way to refer to a context menu in documentation?

It used to be that you could tell a user (in documentation or in onscreen prompts) to, let's say, "Click a button, or right-click to display a menu." Nowadays, there are multiple ways to display a ...
Alan M.'s user avatar
  • 143
4 votes
3 answers
3k views

How to best spec animations/transitions for engineering team handoff

I have an app prototype built using Pixate which demonstrates the entire flow of the app I am working on. There are transitions between views and animations for certain elements on the page. I have ...
Aaron James's user avatar
4 votes
3 answers
1k views

What is the correct way to reference GUI controls when writing content and copy

I'm writing documentation. It's technical documentation and my audience should be tech-savvy. However, I have reservations about referring to UI elements in an interface by the terminology that ...
Roger Attrill's user avatar
4 votes
1 answer
1k views

Disabled button or enabled button with potential error message for actions with complex logic behind?

Say I have a button for a complex state machine which can be disabled for a number of reasons. I feel if I run some business logic CanActionBeDoneNow() and simply disable the button if it returns ...
Nilzor's user avatar
  • 143
4 votes
2 answers
270 views

Idea to enhance the UX and the legibility of an internship report

I am in the last month of my last internship of my IT studies. And as in the five last years, I have to write an internship report (that almost nobody will ever read). The last one. And to give a ...
Pierre's user avatar
  • 143
4 votes
2 answers
115 views

Is there a specific name for not getting back to the same content?

So we're working on a new social media app, and when discussing with the team the analysis and insights for different social media sites, we came to this one you can see on several sites,most ...
Devin's user avatar
  • 37.9k
3 votes
4 answers
152 views

How would I instruct a reader to push a button with an ellipsis at the end?

I am writing some documentation and want to instruct a user through a process. During the process the user should click a button to open another screen. I am unsure how to document this as the ...
user avatar
3 votes
2 answers
1k views

Updating technical specifications after requirements changed?

We are working on a really large project. After we have created the wireframes and wrote the technical specification we started designing, slicing and programming. Technical specifications were ...
Oleg's user avatar
  • 741
3 votes
1 answer
216 views

How do you describe "animation effects" in your Interaction Design? And in which phase do you do this? [closed]

Question: How and when do you describe the animation effects (or rather gimmicks) in your interaction design? Description: With animation effects/gimmicks i mean stuff like, "When i hover my mouse ...
DennisW's user avatar
  • 1,069