Merge pull request #78 from marcuspollio/designguide-format1

Cleanup Design Guide 1

designguide/elements.md

@@ -3,17 +3,13 @@
 - [Toolbars](#toolbars)
 
 - [Dock Windows](#dock-windows)
-
-  - [Task Panels](#task-panels)
 
-### 
+  - [Task Panels](#task-panels)
 
 ## Toolbars
 
 Toolbar management in complex technical software such as CAD poses unique challenges as there are often hundreds of potential tools, functions, or features which may require ready access within the GUI. The [Pareto-Principle]((laws-of-ux.md#pareto-principle)) (80/20 rule) should be the basis for how toolbars are populated. The 80/20 rule states that 20% of the input results in 80% of the output. This would imply that 20% of a set of tools get 80% of the use. While this may not be a perfect correlating principle, it should help guide a critical thought process about which tools go onto a toolbar and also how they are organized.
 
-#### 
-
 **Toolbar Organization Guidelines:**
 
 - Inverse functions (example: functionally similar additive and subtractive operations) should be combined into single tools wherever practicable. Switching between inverse modes should be done with a boolean control such as a toggle/checkbox within the related TaskPanel rather than resulting in separate tools. It minimizes space on toolbars and simplifies icon development.
@@ -22,8 +18,6 @@ Toolbar management in complex technical software such as CAD poses unique challe
 
 - Toolbars should be broken into logical groupings, both visually(iconography), and functionally. Avoid use of many specialized toolbars in favor of more moderate sized toolbars. ie. one for basic functionality, and one for advanced. (80/20 rule helps here as well. Ideally there would be no more than 3 QToolBars in horizontal orientation or 2 toolbars in a vertical. Those are not hard requirements however.
 
-### 
-
 **Toolbar Buttons:**
 
 - Should consist of only QToolButton or QMenuButton widgets. Other widgets may be used in special circumstances. The developer must ensure that the introduced widget is visually consistent and does not stand out above other tools. Features adding custom widget to toolbars shall be reviewed by the design working group.
@@ -32,30 +26,23 @@ Toolbar management in complex technical software such as CAD poses unique challe
 
 - Deviations in prescribed widget types allocated to a tool bar must only be accepted after consensus is reached between applicable developers and a thorough review by the design team.
 
-### 
-
 ## Dock Windows
 
 These are the dockable panels that typically reside docked to the left, right or bottom edges of the FreeCAD UI.
 
-#### 
-
 #### Task Panels:
 
-These panels are a quintessential component of FreeCAD's interface. A task panel is the means by which a user interacts with the current task being performed. Ranging from controlling sketch elements, defining parameters for a feature such as a Chamfer or set up parameters for CNC machining. These critical components <u>*must*</u> be uniform in both layout and sizing. A default width, in accordance with the UI [zones and layout](zones.md) definitions is established at 360 pixels.
-
-###### 
+These panels are a quintessential component of FreeCAD's interface. A task panel is the means by which a user interacts with the current task being performed. Ranging from controlling sketch elements, defining parameters for a feature such as a Chamfer or set up parameters for CNC machining. These critical components **must** be uniform in both layout and sizing. A default width, in accordance with the UI [zones and layout](zones.md) definitions is established at 360 pixels.
 
 Here are general guidelines to be followed for a task panel:
 
-- "Ok" and "Cancel" buttons *shall* be located at the top of each panel with a centered alignment.  Alternative button configurations are inconsistent and not acceptable.
+- "Ok" and "Cancel" buttons *shall* be located at the top of each panel with a centered alignment.\
+Alternative button configurations are inconsistent and not acceptable.
 
 - Minimize the width of the panel as much as possible through good use of space, arrangement of widgets, and [naming](naming.md).
 
-- Developers should use the approriate [interactive control](interactive.md) widgets to ensure a consistent experience throughout 
+- Developers should use the approriate [interactive control](interactive.md) widgets to ensure a consistent experience throughout
 
 - Task Panels can potentially include enormous amounts of information and advanced settings/controls. Utilizing FreeCAD's custom [QSInt](https://freecad.github.io/SourceDoc/d9/d11/namespaceQSint.html) widget class, which provides a 'rolling up' of portions of the panel, is encouraged. Follow the [80/20 rule](laws-of-ux.md#pareto-principle), and by default only expose the most commonly needed controls/data to avoid overwhelming users with information/settings when they are not needed. This allows the user to expand more advanced settings, controls or information when the need arises.
 
-## 
-
 [Return to Design Guide Main Page](index.md)

designguide/glossary.md

@@ -12,6 +12,4 @@
 
 - **Design guidelines:** Guidelines are descriptive written and illustrated docs that demonstrate usage and behavior mainly through examples. They're the long-form discussion of specs that help designers and developers with problem-solving and decision-making.
 
-##
-
 [Return to Design Guide Main Page](index.md)

designguide/history-and-purpose.md

@@ -6,6 +6,4 @@ This *Design Guide* is intended to present developers/designers a series of conc
 
 This guide is the product of a Design Working Group consisting of community members; ensuring decisions made regarding the User Interface and User Experience are consistent with the needs of people who actually use FreeCAD in both professional and hobbyist environments. This working group will also be involved with review of interface/experience related changes to FreeCAD to provide input to developers and maintainers regarding the merits and consistency of features which may impact interaction and/or workflows.
 
-##
-
 [Return to Design Guide Main Page](index.md)

designguide/index.md

@@ -14,7 +14,7 @@
 
 - [Primary Elements](elements.md)
 
-- Interactive Controls 
+- Interactive Controls (Still under development)
 
 - [Naming Convention](naming.md)
 
@@ -24,17 +24,11 @@
 
 - Icons/Art (Still under development)
 
-####
-
 *The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt).*
 
-#### 
-
 ## How to use this guide:
 
-This guide is organized into multiple documents as outlined above, for the purpose of aiding developers in finding relevant content without excess information. Newcomers to FreeCAD, and this Design Guide, should familiarize themselves with the principles and assumptions which were used as the foundation on which these guidelines were built before progressing to more targeted content. The rest of the sections are organized in a manner of logical hierarchy of concepts and guidlines starting with more conceptual matter and moving on towards greater levels of detail. 
-
-#### 
+This guide is organized into multiple documents as outlined above, for the purpose of aiding developers in finding relevant content without excess information. Newcomers to FreeCAD, and this Design Guide, should familiarize themselves with the principles and assumptions which were used as the foundation on which these guidelines were built before progressing to more targeted content. The rest of the sections are organized in a manner of logical hierarchy of concepts and guidlines starting with more conceptual matter and moving on towards greater levels of detail.
 
 ## Assumptions:
 
@@ -44,8 +38,4 @@ According to the [*Steam monthly hardware survey*](https://store.steampowered.co
 
 **Note:** For operating system specific elements Windows is considered the standard due to market share (70% in 2023). Every effort should be made to maintain a uniform appearance across platforms.
 
-**Note:** Deviations from the prescriptive guidelines in this design document require justification utilizing sound reasoning and require a design review that such deviation(s) are both warranted and fit within the needs of the user without degrading the overall consistency of the user experience.
-
-#### 
-
-# 
+**Note:** Deviations from the prescriptive guidelines in this design document require justification utilizing sound reasoning and require a design review that such deviation(s) are both warranted and fit within the needs of the user without degrading the overall consistency of the user experience.