[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    [websites/hig-kde-org] source/patterns/content: Improve Content Patterns' text and formatting consis
From:       Nate Graham <null () kde ! org>
Date:       2018-09-11 23:57:33
Message-ID: E1fzsXF-0005RU-Uo () code ! kde ! org
[Download RAW message or body]

Git commit 1201931b62550145a823d03ec77eb2cbe0a26699 by Nate Graham.
Committed on 11/09/2018 at 23:57.
Pushed by ngraham into branch 'master'.

Improve Content Patterns' text and formatting consistency

Summary:
- Adopted the very compelling "When to use/how to use/implementation" formatting used \
                for most Command and Navigation patterns.
- Updated and improved text

Test Plan: Built locally and read through everything.

Reviewers: #kde_human_interface_guidelines, fabianr

Reviewed By: #kde_human_interface_guidelines, fabianr

Subscribers: fabianr

Differential Revision: https://phabricator.kde.org/D15365

M  +31   -41   source/patterns/content/duallist.rst
M  +29   -38   source/patterns/content/form.rst
M  +6    -9    source/patterns/content/help.rst
M  +11   -7    source/patterns/content/iconandtext.rst
M  +63   -67   source/patterns/content/settings.rst
M  +20   -10   source/patterns/content/viewingediting.rst

https://commits.kde.org/websites/hig-kde-org/1201931b62550145a823d03ec77eb2cbe0a26699

diff --git a/source/patterns/content/duallist.rst \
b/source/patterns/content/duallist.rst index f5b5979..2d99f72 100644
--- a/source/patterns/content/duallist.rst
+++ b/source/patterns/content/duallist.rst
@@ -1,68 +1,60 @@
-Duallist
-========
+Dual-list
+=========
 
-Purpose
--------
+.. image:: /img/TwoLists.png
+   :alt: twoLists.png
 
 Multiple selection in lists with more than a few items might become
 difficult because selected as well as available items are not visible at
-once. As an alternative approach the *dual-list pattern* (also known as
+once. As an alternative approach, the *dual-list pattern* (also known as
 list builder, or paired lists) was introduced. It consists of two
 standard list boxes with the option to move items from one list to the
 other and back. Dual-lists are useful for extended multiple selection in
 general, especially for huge sets of items or in case of elaborate
 selections. The trade-off is the rather large amount of space that is
-needed to show two adjoined lists.
+needed to show two adjoining lists.
 
-Example
--------
-
-.. image:: /img/TwoLists.png
-   :alt: twoLists.png
-
-Guidelines
-----------
-
-Is this the right control
-~~~~~~~~~~~~~~~~~~~~~~~~~
+When to use
+-----------
 
 -  Use a dual-list pattern for multiple selection and in case of large
    lists.
--  In case of limited screen real estate consider to change the workflow
+-  In case of limited screen real estate, consider changing the workflow
    into repeated selections of smaller lists or by applying a hierarchy
    to the data.
--  Do not use a dual list to show data primarily.
+-  Do not use a dual-list to show data primarily.
 
-Behavior
-~~~~~~~~
+How to use
+----------
 
--  Make the left list the standard list containing all available
-   options. The right list holds all currently selected items.
+-  Label both lists view with a descriptive caption to the top. End each list
+   label with a colon.
+-  Use the left list  to contain all available options. The right list
+   should hold all currently active or in use items.
+-  Ensure that the list boxes are of equal height and width.
 -  Place move/remove buttons (right and left arrows) centered and in
-   between the two lists.
--  Disable a button if the respective list is empty.
--  Provide drag ‘n drop of items between lists.
--  Double click on an item adds it to the current list, or removes it
-   respectively.
--  Allow multiple selection of items within one list.
+   between the two lists. Disable a button if the list it is pointing away
+   from is empty.
 -  If an instance of one item can be repeated (such as a spacer), copy
    (rather than move) the item from the available pool of items to the
    list of current items.
 -  If the list of current items can be reordered, place up/down buttons
    to the right of the list of current items. Only enable the up/down
-   buttons when an item is selected and can be moved. Drag and drop may
-   also be used in addition to reorder the list.
--  Do not have blank list items; use meta-options, e.g. (None) instead.
--  Place options that represent general options (e.g. All, None) at the
+   buttons when an item is selected and can be moved.
+-  Do not have blank list items; use meta-options, (e.g. "None") instead.
+-  Place options that represent general options (e.g. "All", "None") at the
    beginning of the list.
--  Sort list items in a logical order. Make sure sorting fits
-   translation.
+-  Sort list items in a logical order. Alphabetical sorting should be able
+   to change when the text is translated.
 
-Appearance
-~~~~~~~~~~
+Implementation
+--------------
 
--  Ensure that the list boxes are of equal height and width.
--  Alternate row color (use theme settings).
+-  Allow the user to drag-and-drop items between lists, or re-order items
+   within a list (if applicable)
+-  Double clicking on an item should add it to or remove it from the current
+   list, respectively.
+-  Allow multiple selection of items within one list.
 -  Make both list controls large enough that it can show at least four
    items at a time without scrolling.
 -  If the lists appears in a dialog or utility window, consider making
@@ -70,8 +62,6 @@ Appearance
    choose how many list items are visible at a time without scrolling.
    Each time the user opens this dialog, set its dimensions to those
    that the user last resized it to.
--  Label both lists view with a descriptive caption to the top.
 -  Create a buddy relation so access keys are assigned.
--  End each list label with a colon.
 -  Use :doc:`sentence style capitalization </style/writing/capitalization>`
    for list view items.
diff --git a/source/patterns/content/form.rst b/source/patterns/content/form.rst
index 4f90068..b8899fb 100644
--- a/source/patterns/content/form.rst
+++ b/source/patterns/content/form.rst
@@ -1,15 +1,27 @@
 Form
 ====
 
-Guidelines
-----------
+A *Form layout* is used to help align and structure a layout containing many
+control and input fields.
+
+When to use
+-----------
 
+-  Use a Form layout when there are many related controls and input fields.
+-  Form layouts are ideal for :doc:`settings dialogs </patterns/content/settings>`.
 
-Labels on the left
-~~~~~~~~~~~~~~~~~~
+How to use
+----------
 
-On |desktopicon| Desktop it is recommended to place the labels to the left
-of the connected widgets.
+-  On |desktopicon| Desktop it is recommended to place the labels to the left
+   of the connected widgets. Labels that are to the left of their connected
+   widgets should be right-aligned and end with a colon (in case of
+   right-to-left languages, mirror the alignment). This makes the whole group
+   of form widgets appear to be center-aligned. In Qt 5, using a QFormLayout handles \
all of this for you automatically. +-  See the pages on
+   :doc:`radio buttons </components/editing/radiobutton>` and 
+   :doc:`checkboxes </components/editing/checkbox>` for detailed information
+   regarding how to align these tricky controls in a Form layout.
 
 .. container:: flex
 
@@ -29,19 +41,6 @@ of the connected widgets.
          :noblefir:`GOOD` |br|
          Plasma 5 form alignment
 
--  The labels that are to the left of their connected widgets should be \
                right-aligned.
-   This makes the whole group of form widgets appear to be center-aligned.
-   In Qt5, using a QFormLayout handles this correctly for you.
-
-Controls
-~~~~~~~~
-
--  Align groups of items vertically rather than horizontally, as this
-   makes them easier to scan visually. Use horizontal or rectangular
-   alignments only if they greatly improve the layout of the window.
--  Align a group of widgets to the left. This makes use of space more
-   efficiently.
-
 .. container:: flex
 
    .. container::
@@ -60,8 +59,10 @@ Controls
          :noblefir:`GOOD` |br|
          Plasma 5 form alignment
 
--  Left align controls over multiple groups (in case of right-to-left
-   languages mirror the alignment). The visual anchor facilitates
+-  Position groups of items vertically rather than horizontally, as this
+   makes them easier to scan visually. Use horizontal or rectangular
+   positioning only if it would greatly improve the layout of the window.
+-  Left align controls over multiple groups. This visual anchor facilitates
    scanning of content, and left-hand alignment fits as well forms that
    have been oversized individually.
 
@@ -83,9 +84,10 @@ Controls
          :noblefir:`GOOD` |br|
          left aligned controls
 
--  Keep track on label size; avoid big differences in text length (even
-   after translation), that could result in much whitespace for
-   multiple aligned controls.
+-  Keep track of label sizes; avoid big differences in text length that could
+   result in too much whitespace for multiple aligned controls. Keep
+   translation in mind too; existing length differences will be exaggerated
+   for wordy languages such as German and Brazilian Portuguese.
 
    .. figure:: /img/Form_Align_Long.qml.png
       :scale: 80%
@@ -93,21 +95,10 @@ Controls
       :iconred:`BAD` |br|
       Avoid very long captions
 
-Labels on top
-~~~~~~~~~~~~~
-
-For |mobileicon| mobile, or if only narrow space is available, it is
-recommended to place the labels above the connected widgets.
+-  For |mobileicon| mobile, or if only narrow space is available, it is
+   recommended to place the labels above the connected widgets.
+-  When using labels on top, labels and widgets should be left-aligned.
 
 .. image:: /img/Form_Align_YES_Mobile.qml.png
          :scale: 80%
 
--  Labels and widgets align left
--  Minimize label length. Avoid multi-line labels.
-
-Checkboxes and Radio buttons
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For more details on alignment of 
-:doc:`radio buttons </components/radiobutton>` and 
-:doc:`checkboxes </components/checkbox>`, see the detailed HIG pages.
diff --git a/source/patterns/content/help.rst b/source/patterns/content/help.rst
index 8d50565..772be8c 100644
--- a/source/patterns/content/help.rst
+++ b/source/patterns/content/help.rst
@@ -1,20 +1,13 @@
 Help system
 ===========
 
-Purpose
--------
-
 The *help system* should be used as a secondary mechanism to support
 users' complete and better understanding of tasks — the primary
 mechanism should be the user interface itself. Users consult the help
 system only if they can't accomplish a task with the UI.
 
-Examples
---------
-
-Guidelines
-----------
-
+When to use
+-----------
 Try to make Help unnecessary in the first place:
 
 -  Make common tasks easy to discover and perform.
@@ -26,6 +19,10 @@ Try to make Help unnecessary in the first place:
    preventing errors.
 -  Write error messages that provide a clear solution or action for the
    user to take.
+
+How to use
+----------
+
 -  Usually, the help system is activated by F1 respectively Ctrl+F1 for
    context sensitive information and via menu.
 
diff --git a/source/patterns/content/iconandtext.rst \
b/source/patterns/content/iconandtext.rst index a771e6c..00eaf3c 100644
--- a/source/patterns/content/iconandtext.rst
+++ b/source/patterns/content/iconandtext.rst
@@ -1,26 +1,30 @@
 Icons and text
 ==============
 
-Purpose
--------
+When to use
+-----------
 
 Combining icons and text can be used to identify data and actions in a
 user interface. Examples include toolbar actions, file and folder
 displays in a file manager, application listings, and notifications. The
 layout should be consistent.
 
-Guideline
----------
+How to use
+----------
 
 .. image:: /img/HIGPatternIconsAndText.png
    :alt: Alignment of text and icons.
 
 .. attention::
-   Make sure to read about how :doc:`units and messurements </layout/units>` are \
used for design and development. +   Make sure to read about how :doc:`units and \
measurements </layout/units>` are used for design and development.  
 -  Where icons are shown with text, use the layout guidelines above.
+
+Implementation
+--------------
+
 -  For 16x16px icons and smaller, the 8px margins may be reduced to 4px.
--  If Secondary Text is normally present, but is empty in a particular
-   instance, align the Primary Text to the vertical center.
 -  Where icons are shown without text, always provide tooltip text and
    alternate text for accessibility.
+-  If Secondary Text is normally present, but is empty in a particular
+   instance, align the Primary Text to the vertical center.
diff --git a/source/patterns/content/settings.rst \
b/source/patterns/content/settings.rst index a6abecd..bf990d5 100644
--- a/source/patterns/content/settings.rst
+++ b/source/patterns/content/settings.rst
@@ -1,87 +1,83 @@
 Settings
 ========
 
-Purpose
--------
+A *settings page* provides the ability to customize how an application or
+Plasma widget should behave. It is intended for settings that are persistent but not \
changed very frequently. Following KDE's "Simple by +default, powerful when needed" \
:doc:`design mantra </introduction/vision>`, +settings are split into common and \
advanced groups. Advanced settings are +not important to most users but essential for \
some, and therefore can't be +removed. Those settings are hidden by default to reduce \
the mental overhead +of using the settings page, but with easy access.
 
-The settings dialog provides user-customizable options how an
-application or plasma (KCM) should behave. The dialog is intended for
-options that are not accessed frequently and are persitent. Following
-KDE's "Simple by default, powerful when needed" 
-:doc:`design mantra </introduction/vision>`, settings are split 
-into simple vs. advanced ones. Advanced settings are
-options that are not important to most users but essential for some, and
-can't removed therefore. Those options are hidden by default, but with
-an easy access in order to improve learnability.
+When to use
+-----------
 
-Guidelines
-----------
-
-Is this the right control
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
--  Use this pattern for all settings that are relevant to change for
-   users.
--  Do not use the settings dialog for frequently accessed properties
-   like, for instance, details vs. icon view. Use the toolbar or main
-   menu (and optionally context menu) for these options.
--  Do not use the settings dialog for rarely changed or developer
-   options like the sql table name. Use extra configuration files or
-   dialogs for those options.
+-  Use the settings page to display settings that are persistent but not
+   accessed or changed very frequently. A the toolbar or the main menu (and \
optionally context menus) are more appropriate places for settings that +   are \
frequently accessed and changed, such as icon view style or sort order. +-  Do not \
use settings pages to change the properties of a selected item. +   Instead, use a \
properties dialog or a contextual editing panel. +-  Do not use the settings page for \
potentially dangerous developer settings +   like the name of an SQL table. Instead, \
use configuration files or separate +   dialogs.
 
-General recommendations
-~~~~~~~~~~~~~~~~~~~~~~~
+How to use
+----------
 
--  Simple by default: Define smart and polite defaults. Set the defaults
-   in a way that most users don't have to alter them at all.
--  Powerful when needed: Provide enough options for the perfect
+-  **Simple by default**: Define smart and polite defaults so that your target
+   :doc:`personas </introduction/personas>` don't have to alter them at all.
+-  **Powerful when needed**: Provide enough settings for the perfect
    customization according individual needs and preferences. But even
    though customizability is very important for KDE software, try to
-   keep your settings dialog as small and simple as possible. Remember:
-   every option requires more code and more testing!
+   keep your settings page as small and simple as possible. Remember:
+   every option requires more code and more testing, and makes the settings
+   page slower to use.
 -  Respect the privacy of the users: Always use opt-in, never an opt-out
    model for features that transmit potentially private data (e.g. usage
    statistics).
 
-Layout
-~~~~~~
-
--  Organize your settings in logical groups. (#1 in the example).
--  Split options per group into standard and advanced. Make the standard
-   easy to use for everyone. (#5)
--  Offer several pre-defined profiles or schemes, and let the user
-   decide what type of configuration should be active. (#3)
--  Consider to add access to third-party profiles/schemes via Get Hot
-   New Stuff! (use the label "Get New [term used for profile in your
-   case]s"), if available for this group. (#4)
--  Show a live preview for visual features. Omit this section if it's
-   not relevant.
--  Provide functions to export/import all settings. (#7) If splitting
-   the options into app-related (such as colors, fonts, etc.) and
-   account-related (for instance personal settings, mail accounts...)
-   make sense, let the user decide what to export. Import has to as
-   straightforward as possible; let the user just confirm when data are
-   being overwritten.
+Implementation
+--------------
 
-Behavior
-~~~~~~~~
+-  For a desktop app, put your settings page inside a dialog window and do not
+   allow it to have a vertical or horizontal scrollbar because all of the
+   content will not fit. Instead, separate your controls into more groups and
+   make use of :doc:`tabbed views </components/navigation/tab>`. This does not apply \
to scrollbars within inline tables and grid views, which are +   acceptable.
+-  On mobile, use a full-screen view for your settings page. Vertical scrolling
+   is acceptable.
+-  Lay out your settings page according to the
+   :doc:`alignment </layout/alignment>` guidelines. The overall layout
+   should appear to be centered, with with section labels on the left side,
+   and controls on the right. Tables and grid views are the exception, and
+   should span the window width.
+-  Organize your settings into logical groups, with more important groups
+   appearing higher up on the page. Separate the groups with whitespace or
+   put them into different tabs of a
+   :doc:`tabbed view </components/navigation/tab>` (if appropriate).
+   Try to avoid the use of group boxes to distinguish sections.
+   (#1 in the example)
+-  Separate common and advanced settings into different groups. If necessary,
+   hide the advanced settings behind a collapsible group box. Make the
+   standard settings comprehensible and easy to use. (#5)
+-  Consider adding access to third-party add-ons via Get Hot New Stuff!,
+   if available for this group. Use the label "Get New [term used for
+   add-on content]s" (#4)
 
--  When the user changes the default switch to a special profile ("User"
-   or "Current"). This profile cannot be applied unless it is renamed
-   individually. Access to rename (and delete) is done per context menu.
-   Indicate user-defined profiles by using italic font for the name.
--  Sort your options and groups by importance.
 -  When a change is applied, the application should adopt it immediately
    without the need to restart it.
--  Do not change the settings dialog depending on the context. You
+-  Do not change the settings page depending on the context. It
    should always start with the same landing page regardless of the
    application context.
--  Do not use a wizard to edit options. Only use a wizard to set options
-   if actually a group of options all have to be edited at once, eg
-   creating an account or a first run wizard.
--  Do not hide options conditionally. Don't make a user guess what
-   options need to be changed to have other options available. Disable
-   options instead and hint the user why the options are disabled.
+-  Do not use a wizard to change settings. Only use a wizard if a group of
+   settings are all interrelated and must be edited all at once, e.g.
+   setting up an email account.
+-  If some of the program's settings are only applicable in certain contexts,
+   do not hide the inapplicable ones. Instead, disable them and hint to the
+   user why they're disabled.
+   **Exception:** it is acceptable to hide settings for non-existent hardware.
+   For example, it's okay to hide the touchpad configuration when no touchpad
+   is present.
 
 Mockup
 ~~~~~~
@@ -105,8 +101,8 @@ Mockup
    Organize the setting in a way that GHNS access is per group and not
    global.
 #. Provide access to the most relevant settings at the Standard section.
-   Make sure that these options are easy to understand.
-#. Indicate that Advanced options are available but keep this section
+   Make sure that these settings are easy to understand.
+#. Indicate that Advanced settings are available but keep this section
    collapsed by default. Use a descriptive label so that it reflects the
    functionality.
 #. Allow users to export the current settings to a file that can be
diff --git a/source/patterns/content/viewingediting.rst \
b/source/patterns/content/viewingediting.rst index da5e765..cdac168 100644
--- a/source/patterns/content/viewingediting.rst
+++ b/source/patterns/content/viewingediting.rst
@@ -1,16 +1,23 @@
 Viewing vs editing 
 ==================
 
-Purpose
--------
-
-In most cases information should be presented for viewing not editing.
-Presenting input controls to the user when they are not needed creates
-unnecessary clutter and distraction, interfering with effective
+In most cases, information should be presented by default for viewing,
+not editing. Presenting input controls to the user when they are not needed
+creates unnecessary clutter and distraction, interfering with effective
 presentation of the information.
 
-Guideline
----------
+When to use
+-----------
+
+Only show editing controls when appropriate. Examples include:
+
+-  When an item is selected, contextually-appropriate editing controls can be
+   shown in a toolbar or panel.
+-  If an explicit editing mode is appropriate, then editing controls should
+   not be shown until that mode is activated.
+
+How to use
+----------
 
 .. image:: /img/ViewMode.png
    :alt: Viewing
@@ -24,13 +31,16 @@ Guideline
    layout and the contact name is set in large type to direct the users
    eye to next piece of information.
 -  Provide a separate mode for editing the data when requested by the
-   user (via a button, toolbutton or menu item).
+   user (via a button, toolbutton or menu item):
 
 .. image:: /img/EditMode.png
    :alt: Editing
 
 -  Alternatively, in-line editing can be provided to edit a single data
-   element at a time.
+   element at a time when it is clicked on or selected:
 
 .. image:: /img/PartialEditMode.png
    :alt: Line-in editing
+
+Implementation
+--------------


[prev in list] [next in list] [prev in thread] [next in thread]