Questions tagged [documentation]

text, usually about how to use a program.

Filter by
Sorted by
Tagged with
28
votes
7answers
3k 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 ...
34
votes
5answers
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 ...
0
votes
3answers
213 views

Best way to present and document long screens

Currently I am using tools like Word, Powerpoint and Keynote to present concepts and specs to stakeholders. What is the best – or optimal – way to present and document long screens for stakeholders? ...
3
votes
2answers
117 views

How do you manage change of language/terminology in a scalable way for documentation (internal communication)

As UX Designers, we change and create words for things in the UI. Sometimes those are labels, sometimes error messages etc. I've found it very difficult to keep documentation - say confluence up to ...
35
votes
2answers
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 ...
1
vote
2answers
119 views

Recommended patterns for help cues/hints/documentation

I've been scouring the web, but haven't been finding much with regards to different options on how to present help text and/or documentation. Obviously, there's an established pattern of just having a ...
0
votes
3answers
140 views

When providing programming documentation to users of an office suite software, does intelligent cell merging in tables, make the info more accessible?

Examples of such merged-cell use, alongside versions of same info without merged-cell use Info using merged cells Table 1 Table 2 Same info without using merged cells Table 1 Table 2 Background ...
1
vote
1answer
88 views

User experience and Agile Modeling

I have a question regarding architect modeling and how an UX designer can use them to deliver better documentation to the developers/software architects. Has anyone used a component diagram to ...
13
votes
5answers
7k 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 ...
3
votes
1answer
162 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 ...
1
vote
0answers
33 views

Business Software and Policies/Usage Hints

We use business software of all kind (CRM, ERP,...). There are lots of things to remember for fluent usage as keyboard shortcuts, company usage guidelines, colleagues hints, software manuals, internal ...
15
votes
6answers
23k 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 ...
9
votes
4answers
4k 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?
0
votes
1answer
67 views

documenting a web app [duplicate]

My company is trying to improve the UX in our system. It's web based app, full with features. The system development started 8 years ago, but it was never documented, and our programmers/support team ...
2
votes
4answers
132 views

Tech Writing: What to call list columns?

I'm currently re-writing some software documentation for users, and I'm stuck on how to label the columns on this page, which lists files that you've recently exported from the system, with various ...
1
vote
1answer
97 views

What frameworks exists for UI documentation?

I´m working on a style guide which I want to put on the web with info, examples etc. I know there is one API / framework called Fractal, but it does not have the look and feel I want. I see a lot of ...
8
votes
3answers
756 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 ...
0
votes
1answer
94 views

Usability or Accessibility

Overview I am writing some UX Guidelines for our organization which is a Software as a Service business. Our organization relies heavily on Presentations, Marking Material, as well as our Software. ...
0
votes
2answers
131 views

How to describe elements/widgets properly?

We are making widgets for a corporate website and I'm trying to figure out the best way to describe them. Something like writing a documentation. There are at least 10 of these, but here is one ...
2
votes
1answer
3k views

Annotating wireframes in sketch - how do you do it? [closed]

I've been using the notebook pro plugin for the past few months, but I'm running into tons of issues. (crashes, random inability to add new comments in larger docs, etc) What are other techniques for ...
13
votes
4answers
394 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?
18
votes
3answers
38k 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.
3
votes
1answer
92 views

How often should the same hyperlink appear in a document?

I was reading a blog post today that made me question how often a hyperlink to the same content should appear in a document. In the post, nearly every reference to HDL (with the exception of one ...
2
votes
2answers
213 views

Characteristics of UX briefs

In your experience, what should a good UX brief include? What is the information you need to start work on a project?
1
vote
1answer
795 views

What is the main difference in between a UI KIT and a Styleguide?

We are working on documenting visual design and I wanted to know: what is the main difference between a UI KIT and a styleguide? Is the difference between them that the styleguide includes design ...
1
vote
1answer
86 views

How to design configurable scripts for non-programmers [closed]

I have a python script that allows users to parse addresses when batch-editing a table. The script allows the user to choose whether to return the house number or the street name to the field (by ...
2
votes
3answers
162 views

How should I demonstrate a choice between two options in step-by-step instructions?

I'm writing a step-by-step employee guide for logging into a course management program. I need to demonstrate that one of the steps will differ depending on where the employee is logging in from. To ...
2
votes
3answers
131 views

What's worse: no user guide or a useless user guide?

I work on UX team designing a massive, technically-complex, operations application. Difficult enough to comprehend that documentation will help many users, even if the UX is as intuitive and easy to ...
1
vote
1answer
178 views

Documentation in one page or different pages?

What way should the documentation of a site be, all in one page or split into different pages? Since I think it is relevant, this is my project documentation right now, a library for Node.js ...
1
vote
1answer
139 views

Screen shot of all google.com oneboxes

Can anyone provide the URL for an illustration of an exhaustive set of google.com oneboxes? Background: Below is a SERP screen shot highlighting google.com's way of grouping content types, which some ...
1
vote
1answer
83 views

UX documentation

How do you refer to "the user" in your wireframe notes and specs? Do you write it as: "I start typing", or "the user starts typing"? What format do you use? Also, does anybody have any examples from ...
12
votes
6answers
7k 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 ...
2
votes
3answers
630 views

How to approach user documentation in a maintainable, but user-friendly way?

Question What approach should be taken when designing end-user documentation for a large/corporate (web-based) software system? Is there industry best-practice that combines good UX with ...
3
votes
2answers
364 views

User Manual vs How-to guide?

I am working on specifying documentation for a soon to be released SaaS tool. Some parts of it are very technical and will require an in-depth explanation of how it works. Conceptually I was ...
1
vote
1answer
138 views

User manual with screenshots for mobile devices?

I'm thinking of a user manual, which documents a web-site-based application. The manual should introduce and explain the functionality (the various pages) of the application. The purpose of the ...
47
votes
6answers
4k 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 ...
2
votes
2answers
387 views

What is the best way to document/describe a completely new product?

Describing a new feature, optimization, or new section of an existing app for engineering and the product team is fairly solvable. You can build on a specific existing point of reference and user ...
1
vote
3answers
71 views

What should I call these navigation buttons?

See image below. These buttons used in an application to move between first, last, next, and previous records. I've seen them referred to as "VCR buttons". As that technology becomes less common (and ...
4
votes
3answers
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 ...
0
votes
1answer
329 views

Customer Journey testing [closed]

I'm new inside UX/CX design field, and I would like to know more info about customer journey mapping. I know that this process is to map the current customer journey also emotional mapping to find ...
4
votes
3answers
685 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 ...
6
votes
1answer
6k 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, ...
3
votes
1answer
51 views

What are best practices for managing terminology changes in legacy software?

In a big redesign, there can be terminology changes and mapping to backend entities that needs to happen. What are the best practices for doing this? Also, for making documentation consistently ...
4
votes
2answers
120 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 ...
1
vote
2answers
105 views

Is video more effective than traditional text help?

Does anyone have experience with users' success or failure in using video or "task recording", as opposed to traditional textual help to complete their task or get more information? Additionally, ...
6
votes
4answers
439 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 ...
12
votes
3answers
654 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 ...
1
vote
3answers
386 views

UX/UI Documentation

In the next few weeks I'll be working on a project that teaches students how to program and design apps for Android Wear, tablets, and TVs. I'll be there as a UI and UX consultant, and will have about ...
1
vote
5answers
999 views

How to write a perfect style guide [duplicate]

I'm developing a sort of a theme with a set of pre build components with is such as, styled data tables, input forms and etc... This is developed for internal usage in my company and I would like to ...
2
votes
1answer
66 views

Is it okay to have a random “notes” section in your documentation?

I started collecting from users of my project about the problems they face while using it and decided to put it into the documentation. Since right now it's just a single "README" document, I put it ...