Noesis Studio: Technical Writing Stlye Guide
Input References
Input Reference RST Format
References to any mechanical inputs should always be written in the monospace format.
Input Reference Employment
Input references can be used in a standalone manner, such as when employed within a table:
| Function | Shortcut |
| Fit Element to Stage | F |
Input references can be included inline as part of a sentence, such as:
| To remove an element from the Navigator, Click on it, then press Del. |
Input Reference Syntax
Actions should always be written with each individual input capitalised, written within square brackets, and spaced from the next input in a sequence. For example:
| Click |
| Ctrl + C |
| Ctrl (Hold) + Shift (Hold) + R |
Simultaneous input combinations should always be combined with the use of a plus (+) symbol, for example:
| Click (Hold) + Drag |
| Ctrl + Shift + S |
Specifiers should be referred to in parenthesis (( )), spaced out from the primary input, for example:
| Alt (Hold) |
| MiddleMouse (Hold) + Drag |
Specifiers which provide the user with multiple options should be separated by a forward-slash (/) symbol, for example:
| MouseWheel (Up/Down) |
Inputs which can be actuated through multiple methods should have each option separated by an or, for example:
| Ctrl (Hold) + D or Alt + Click (Hold) + Drag |
Mouse Inputs
Mouse inputs should be referred to as follows:
| Left-Click | Click |
| Left-Click Double-Click | DoubleClick |
| Left Button Click-and-Drag | Click (Hold) + Drag |
| Right-Click | RightClick |
| Right Button Click-and-Drag | RightClick (Hold) + Drag |
| Mouse Wheel Press | MouseWheel (Press) |
| Mouse Wheel Scroll Up or Down | MouseWheel (Up/Down) |
| Mouse Wheel Scroll Up | MouseWheel (Up) |
| Mouse Wheel Scroll Down | MouseWheel (Down) |
| Mouse Forward Button | MouseForward |
| Mouse Back Button | MouseBack |
Special Keyboard Keys
Non-alphanumerical and/or non-symbol keyboard keys should be referred to as follows:
| Escape | Esc |
| Enter | Enter |
| Shift | Shift |
| Backspace | Backspace |
| Delete | Del |
| Control | Ctrl |
| Alt | Alt |
| Spacebar | Space |
| Caps Lock | Caps |
| Tab | Tab |
Special Formatting
Folder References
References to any folder names should always be written in the monospace format, preceded by a 🗀 (folder) icon, for example:
| Hover over the 🗀 Styles_Fonts folder in the Assets panel. |
File References
References to any generic file names should always be written in the monospace format, with a . suffix, for example:
| Open the .noesis file. |
References to specific file names should follow the same format, but should be preceded by a 🗋 (file) icon, for example:
| A RootGrid can be found within 🗋 MainPage.xaml. |
Text References
References to in-application text should always be written in single quotes, for example:
| Files can be filtered either by name via the 'Search assets' field, or by file type using the filter dropdown menu. |
| Resources can also be created directly from their respective Properties within the Properties Panel of an element, by first setting a value for the Property, then selecting 'Convert to Resource' from within the Property's 3-Dot context menu. |
This convention is not required for references to icons, for example:
| Once the target has been set as active document, the merge function can be accessed hovering over the target file name in the Resources Panel, clicking on the ⊕ (Merge) icon, then selecting the Dictionary to merge into it. |
File Format References
Standalone references to any file formats should always be written in all caps, for example:
| Behind-the-scenes, SVG imports are converted into GeometryData for seamless integration into the XAML framework. |
| Images in the JPG/JPEG and PNG format can be dragged directly to the Navigator. |
Emphasis
When appropriate, bolding can be used to emphasize titles/headers, special warnings, or key words, for example:
About the Noesis Studio Application:
It is important to note that the provided Noesis Studio download for Windows is delivered as a 'portable' application.
|
Please note that installation of both the apppropriate SDK and matching NoesisGUI Plugin are required to pair Studio with your engine. You can find these as downloads, along with their setup guides, in the table below.
|
Method
|
Status
|
Noesis Studio
Standalone Application
|
Available
|
Unity
Direct Integration
|
Coming 2024
|
Footnotes
Special notes that can be included outside of the body of content should be written in superscript Arabic numbers directly to the right of the annotated term, without any whitespace in-between. They should always be numbered in order of appearance. As for the superscript footnote itself, it should then be written surrounded by parenthesis (( )), with the note written in italics, for example:
Lorem ipsum dolor sit amet, consectetur¹ adipiscing elit. Suspendisse pellentesque sodales² orci non volutpat.
(¹) Annotation 1
(²) Annotation 2
|
Application Icon References
When possible, all references to in-application icons should be referred to using an as-close-as-possible approximate icon from the Unicode icon glyphs, followed by a descriptor of the symbol in parenthesis (()), for example:
| Clicking on the 🗑 (Delete) icon to delete an asset via the Assets Panel. |
| Clicking on the + (Add) icon within the Folder Browser grants the ability to create new items which will be added inside of the active folder at the time of invoking the action. |
| Select 'DataTrigger', then press the 🗲+ (Add Trigger) icon. |
Feature Support Notation
Emoji can serve as a highly-visible and highly-visible way to signal support for various features or formats, for example:
Feature
|
Import Compatability
|
Linear Gradients
The ability to render linear gradients composed of multiple colors and multiple opacity stops.
|
Figma: ❌Clipboard, ❌SVG
Adobe Photoshop: ✅Clipboard, ❌SVG
Affinity Photo, Affinity Publisher: ✅Clipboard¹, ✅SVG
|
Asset Type
|
Formats
|
Notes
|
Bitmap
|
✅ PNG
✅ JPG/JPEG
|
Additional notes...
|
Vector
|
🌀 SVG
|
Additional notes...
|
Hyperlink References
External Hyperlinks
External hyperlinks which take the reader away from the Noesis domain should always be prefixed by the `` ↗️`` emoji, followed by a whitespace, and suffixed by the destination, for example:
Learn more about ↗️ Using Rive in Noesis [Rive Official Documentation]
|
Internal Hperinks
Hyperlinks directly integrated into paragraphs which take the reader to another destination within the Noesis or WPF documentation, should be prefixed by 📘 (Docoument), 🎓 (Tutorial) depending on the type of content linked.
Self-Managed Dictionaries can be organized into custom folder hierarchies from the 📘 Assets Panel, using the same methods as other Asset types.
|
The 📑 (Bookmark) emoji should be used if linking to a section within the current page, for example:
When in 'Play' mode, activated by pressing the 📑 'Play' button, the interface being developed offers the ability to preview the interface from the perspective of the end-user, and to experience user-facing interactions.
|
Alternately, pages with special emoji should be prefixed with their emoji.
List Formatting
Ordered Lists
Ordered lists should be used to demonstrate a very specific order of operations to perform. Ordered lists should be written using bolded Arabic Numerals suffixed with a period (.), followed by a whitespace, for example:
1. First Step
2. Second Step
|
However, note that during inline references to an ordered list, bolding should not be used as to delineate between the list, and a reference to the list, for example:
7. Repeat steps 5. through 7. with a the second Button.
|
Ordered List Sub-Steps
In certain cases, ordered lists will require steps within primary steps. In these cases, bolded letters in alphabetical order should be concatenated to the main numerical order, to illustrate the hierarchy between steps, for example.
7. Style Creation
7a. Ensure that the file for the first of the three Style sets is the currently-active file in Studio.
7b. With the file still active, navigate to the Resources Panel.
|
In certain cases, this sytem can be used to illustrate a level of hierarchy deeper than two levels, for example:
1. Step 1.
1a. Step 1, Sub-Step 1.
1aa. Step 1, Sub-Step 1, Sub-Sub Step 1
1ab. Step 1, Sub-Step 1, Sub-Sub Step 2
1b. Step 1, Sub-Step 2.
1c. Step 1, Sub-Step 3.
2. Step 2.
|
Unordered Lists
Unordered lists should be used to clearly separate out multiple parts of a collection in which there is no sense of sequence between the listed items. Unordered lists should be written using a Bullet Point (•), with each point in the list containing a bolded point title, followed by a colon and a whitespace, for example:
Sets the visibility of the entire Path between:
• Collapsed: The Path is not visible, and does not occupy any space in the layout.
• Hidden: The Path is not visible, but occupies the space in the layout it would occupy if it were Visible.
• Visible: The Path is visible, and occupies space in the layout.
|
Language
Regional Format
As US English is used within Noesis Studio, US English should also be employed within all documentation.
Capitalization
Terms which refer to specific items within Noesis Studio, or within the general framework should always be capitalized. This can serve as a useful technique to clarify what is being referred to within an explanation, for example:
| Term | Form | Description |
| Rectangle | Capitalized | Refers to the Rectangle Shape Element within the framework. |
| rectangle | Non-capitalized | Refers to a rectangular shape. |
| Term | Form | Description |
| Style | Capitalized | Refers to a collection of property values which can be applied to Elements. |
| style | Non-capitalized | Refers to a a visual aesthetic. |
In the case of there existing multiple conflicting terms within the framework, extra care should be payed to be specific, for example:
| Term | Form | Description |
| Border Property | Capitalized | Refers to the Border property of a Border Element. |
| Border Element | Capitalized | Refers to the Border Element within the Framework. |
| border | Non-capitalized | Refers to the outline of any visual element. |
In certain cases, capitalized and non-capitalized forms will both appear to be just as correct to use. In these cases, the capitalized form should be used to refer to Studio-specific content, to allow room for an eventual usage of the generic form, for example:
| Term | Form | Description |
| Property | Capitalized | Refers to an Element Property. |
| property | Non-capitalized | Refers to a generic form of 'property' (i.e. synonym for 'attribute', 'ownership', 'real-estate', etc...) |
| Term | Form | Description |
| Element | Capitalized | Refers to an Element Property from the Properties Panel. |
| element | Non-capitalized | Refers to a generic form of 'element' (i.e. synonym for 'part of something', 'scientific element', 'stovetop burner', 'weather' etc...) |
Professional disciplines and job titles should always be capitalized, for example:
| Term | Form | Description |
| Designer | Capitalized | Refers to a professional working in the field of Design. |
| designer | Capitalized | Refers to a visual editor. |
In certain cases, there could be multiple capitalized terms, due to conflicts in rules around capitalizing both professional disciplines, and framework terms. In such cases, steps should be taken to specify this through additional verbosity, for example:
| Term | Form | Description |
| Editor | Capitalized | Refers to a the profession involving planning, coordinating, and revising material. |
| Style Editor | Capitalized | Refers to Noesis Studio's Style Dummy Editor. |
| editor | Non-Capitalized | Refers to the individual responsible for authoring content and/or making changes to content. |
Documentation Writing Style
In the Documentation format, when describing functionality, declarative third-person sentences, using either the present (for universal facts) or future tense (for consequences of actions), for example:
The Assets Panel is used to view and organize supported file types used within a project.
|
This can be completed by either selecting a file (or folder), and performing a Click + Drag of the file (or folder) into the desired new location.
|
To start editing Paths, the Path Selection Tool can be selected either by clicking on it from the Toolbox, or through the A shortcut.
|
Additional anchor points can be added to a Path by continuing to click on empty areas of the Stage with the Path Tool.
|
Tutorial Writing Style
In the Tutorial format, preambles and overviews of the work that will be performed are centered around collaboration, with heavy usage of "We", "Us", and "Our" first-person plural pronouns, written in the future tense, for example:
Our goal will be to create a method through which a user can pick between one of three different typographic styles for their interface.
|
We will create a folder which will be used to contain our individual Styles.
|
A departure from first-person plural pronouns to "you" or "yours" second-person pronouns can be made when the reader must perform an action, or make a choice for themselves, for example:
You can name this folder as you wish, but we will be using 'StyleSwitcher'.
|
When giving specific instructions, the imperative form should be used, for example:
4c. Repeat steps 4a. and 4b. and create an additional two ResourceDictionary files, each with a unique name.
|
Hover over the 'Styles_Fonts' folder in the Assets Panel, press the ⊕ (Add) icon, and select 'New ResourceDictionary' from the context menu.
|
When describing functions or results, declarative sentences should be used, using either the present (for universal facts) or future tense (for consequences of actions), for example:
The page will now appear in the File Browser of the project's root folder.
|
Using a MergedDictionary allows dictionaries from multiple sources and/or locations to be 'merged' into one easy-to-manage intermediary file.
|
Any official Noesis recommendations should be written as "We", for example:
When you are ready to dive into Noesis Studio, and give it a try for yourself, we recommend visiting {URL}.
|
Tables
Single-Header Tables
Tables of content should always have column headers at minimum, for example:
| Column 1 Header | Column 2 Header | Column 3 Header |
| Item A1 | Item A2 | Item A3 |
| Item B1 | Item B2 | Item B3 |
| Item C1 | Item C2 | Item C3 |
| Item D1 | Item D2 | Item D3 |
Double-Header Tables
Tables of content are addtionally able to have row headers as well as column headers, for example:
| Column 1 Header | Column 2 Header | Column 3 Header |
| Row 1 Header | Item A1 | Item A2 |
| Row 2 Header | Item B1 | Item B2 |
| Row 3 Header | Item C1 | Item C2 |
| Row 4 Header | Item D1 | Item D2 |
Inline Media
Generic Inline Media
When used for decorational purposes, or as a support piece for paragraph text, media may be placed inline to the copy without a caption. It should however always be either directly before, or directly after the text that references the content showcased in the media, for example:
A Path's PathGeometry is composed of one, or many PathFigures, which themselves are made up of Path Points, and the Path Segments that join the Points together.
|
The individual PathFigures that make up a particular PathGeometry can be composed of Segments (such as a single line), simple closed shapes (such as a basic square or an ellipse), or complex 'composite' (or 'compound') shapes (such as as a 'donut' shape composed of one ellipse within another).
|
Media Caption Tables
In the majority of cases, each each PNG or GIF should be accompanied by a mini-table directly under it which serves to describe in detail, the operations showcased in the media. The same rules apply to these mini-tables as regular tables. Therefore, they require at minimum a column header, which in most cases will be a first header titled 'Action', and second header titled 'Notes', in which can be found a detailed description of the action showcased, for example:
| Action | Notes |
Moving Resources
|
Moving a Resources to a different Dictionary can be completed by a Click + Drag of the Resource into the desired Dictionary.
|
In some cases, multiple actions may be able to be showcased in a single piece of media. In these cases, one row in the table should be used per action, for example:
| Action | Notes |
Organizing Dictionaries
|
• Self-Managed Dictionaries can be organized into custom folder hierarchies from the 📘 Assets Panel, using the same methods as other Asset types.
• Moving, or renaming Dictionaries will automatically update any references to them from wherever they are used.
|
Deleting Dictionaries
|
• Dictionaries can be deleted by navigating to the 📘 Assets Panel, and clicking on the 🗑 (Delete) icon that appears when hovering over the Dictionary's file.
It is important to note that deleting a ResourceDictionary which contains Resources that are used within the interface, may break certain aspects of their function and/or presentation. It is therefore recommended to first configure their newly-intended properties before deleting the ResourceDictionary.
|
Annotated Media Tables
In certain cases, annotations will be required to point to specific parts of a piece of media. In these cases, a numbering legend should be used, with a match between the circled unicode symbols of Arabic numbers in the media, and those in the table, for example:
| Zone | Notes |
| ① Folder Browser | The contents of the folder selected in the Folder Browser will be shown within the File Browser below. |
| ② File Browser | Displays a list of all files contained within the folder selected in the Folder Browser.
|
Video Annotation
Videos should be annotated with a one-line description of the content showcased within, as well as the behaviour of the video when clicked in parenthesis (( )) for example:
| Noesis Studio Feature Tour (video opens in a new tab) |