/
Making guides (Author)

Making guides (Author)

Owned by Anders Axelsson
Last updated: Dec 10, 2024
11 min read

Before starting this exercise you need to be logged in to 3DSPACE with a user having access to create parts (it is possible to create similar guides if you are missing create part access). Also you need to have the Author extension installed and connected with a repository.

Please comment and provide feedback if something is not clear or needs improvement

Guide creation

A guide is a holder of a series of instructions. It typically guides the user through a process. Each guide should have a short title and a description. The description is used by users to find the right guide so make sure that the description is detailed and contains as many key words as possible. A good practice is to end with describing where the guide is available e.g. “available from the home page of 3dspace”

Exercise 1 - Create a guide

  1. Click “Create Guide”

  2. Fill out a “Title” (typically very short)

  3. Fill out a “Description” (inc when availabile)

  4. (Optional) Give your guide a custom colour

  5. Click Save

Instruction creation

Guides are built up by a series of instructions. You create instructions by point and click in the target application.

YELLOW target selections indicates a target selection using fall-back technology “xpath”. It makes it possible to select any element from the target application and brings flexibility. All yellow selections is not specifically tested, is not supported, might not perform optimal and could stop working as the target platform change or even as the html detail change over sessions. Handle “xpath” selection with caution and avoid if possible. If you find a yellow target you think should be supported let us know, this is the product USP and we are more than happy expand built in configuration.

green target selections indicate a supported target element. Supported target elements are preferred and maintained in the product, you can rely it performs well and continue working as the target platform upgrades. Automated testing is used to ensure quality of green targets over a large number of 3DEXPERIENCE versions.

Exercise 2 - Create an instruction

  1. Click “+” next to the guide (You will directly be taken into target selection mode.)

  2. Select a YELLOW target (ctrl+click or ctrl+space)

    1. Note the xpath selection on top.

    2. Expand the xpath target to view detail.

    3. Modify the xpath (useful for advanced configuration). Add “/../.." to the end of the xpath. What happens?

  3. Reselect a green target

    1. Toggle target highlighting (ctrl+alt, see instruction bar).

    2. Select the top menu add item '+' (see screenshot).

    3. Expand “Topbar menu: add“ and note that there is no xpath modification options (selection details is fully controlled / predefined in the best possible way).

  4. Enter a title e.g. “Click +” and see how the callout preview updates

  5. Enter a description e.g. “Expands the menu“

  6. You can move the panel by pulling the ‘AUTHOR’ tab down and make the callout fully visible. (an alternative is also to switch sides of the panel to the left from the flip option in menu)

  7. Click “SAVE”

  8. Go to “LIGHT MY WAY” tab to test the instruction just as a user would

    1. Activate by toggle slider

    2. Expand to see description

    3. Use the search to match a key word in description

 

Instructions delivered at the right time

Target states and context selection allow authors to control when instructions are shown. Context enable just-in-time instruction delivery and allows for starting or resuming guides at any time (even in the middle of process).

  • A well considered context selection is key to deliver instructions at the right time (and avoid delivering when it should not).

  • Using context is good for performance as it filters instruction from evaluation.

  • One callout at a time is good practice.

Target states: allow you to control when a callout is displayed based on the state of the target itself and is only available for targets that have a state.

Context: allow you to control when a callout is displayed based on the global state of the app. This depends overall on what you currently see not what is selected.

Note: All states are captured during target selection. If you need to enable a different state not in list you need to first put the application in that state and reselect.

Exercise 3 - Context

  1. Click the edit icon on the callout or go to “AUTHOR“ tab, find your instruction (“Click +“) and press the edit icon to the right

  2. Find “Target” state control

    1. Open select to view the options.

    2. Collapsed is default. Why is that?

    3. The slider allows you to disable this target state.

  3. Find “Context” below the description field

    1. From the “Context” list select “My Desk (Home)” to make the instruction available from the home screen only.

  4. Click “SAVE”

  5. Hover the eye in the “AUTHOR“ instruction list to find out the current evaluation state detail of all instructions (this is dynamic as the UI update)

  6. Expand the + menu and see how the eye change

  7. Edit the instruction, change states and test how the eye (or the actual callout behaviour in “LIGHT MY WAY” tab) is affected as you expand the menu or navigate to object pages.

 

Instruction sequences

Guides are built up by instruction sequences. To make the most user friendly guide, good practice is to have one instruction display at a time. Target state and context are not always enough and ad-hoc context selection or sequences are other tools to achieve step-by-step guidance.

Context selection: use target elements to validate state. You can see context selection as ad-hoc context that you define yourself to control visibility. Context selection target states is very useful to build dynamic sequences. Benefits of using context selection for sequencing is that it is state driven which means that users can move back and forward in process or leave and resume or start at any time.

Sequence dependencies: In cases when there is nothing in the UI to use as context for state driven sequencing you can use direct sequencing as last resort. Direct sequencing is dependent on that the sequenced dependency callout has or has not yet shown rather than element state. So to support multiple iterations within the same session you also need to reset the sequence, otherwise the “after” sequence will be valid for that full session. Starting or resuming next session in the middle of such a sequence is not possible.

Exercise 4 - Create Part instructions

  1. Create instruction for “Hover Engineering”

  2. Create instruction for “Hover Part”

  3. Create instruction to “Click Create Part”

  4. Create instruction to “Check AutoName”

    1. Apply appropriate target and app state

  5. Create instruction to “Select production phase”

    1. Apply appropriate target and app state

  6. Create instruction to click “OK“

  7. Test drive process using eye in “AUTHOR” tab

  8. Test drive as user in “LIGHT MY WAY” tab

Exercise 5 - Context selection

  1. Note that the click “OK” button instruction is visible before phase is selected and that phase is visible before auto name is checked. Why?

  2. Edit “Phase” selection instruction

  3. “SELECT CONTEXT” and point at “AutoName”

  4. Use “AutoName” target state to control visibility of phase to display first once “AutoName” is checked

  5. Click “SAVE“

  6. Test using eye and as end user

  7. Edit “Click OK” instruction

  8. Use context selection to make “Click OK” show first as both “AutoName” and “Phase” are properly filled out

  9. Test using eye and as end user

    1. Uncheck “AutoName” back and see the guides automatically adapt

 

Exercise 6 - Sequence dependencies

  1. Edit “Select production phase”

  2. Delete the context selection

  3. Use sequencing to make “Select production phase” display after “AutoName”

  4. Use sequencing to make “Click OK” display after “Select production phase”

  5. Use “Click create part” to reset sequence

  6. Test using eye and as end user

  7. Make sure “Check AutoName“ is checked and “Select production phase” is selected then in the user panel toggle the guide off and on again. Why doesn’t “Click OK” show?

  8. Reflect on the difference. Why is conditionals better? When is direct dependencies the only option?

Other options in the authoring toolset

In real customer setup with a large amount of guides and different situations there are also other options available to consider for making good user friendly guides.

Anchor points: Controls the positioning preference of a callout. Some logic will automatically override preference positioning when suitable.

Tags: Tags are used by consumers to filter out guides of interest to them. A tag could be experience level or typically a role.

Colours: Assigning colour to guides or even individual instructions could be a good way to visually sort or bring extra attention.

Finding the right guide: Some customers record a large number of guides and it could be hard to find the one you are looking for. To help users find guides there is a search tool. The search tool filters on all callout text content and guide description. Currently it requires an exact match but a more smart semantic search is planned. To increase chance of users finding guides provide a rich description using many different key words. It is good practice to end with describing where the guide is available e.g. “available from the home page of 3dspace”

Callout types: For different scenarios different callout types make sense. Authors can select among several different types.

Performance: The server mainly acts as a repository of configuration and all instructions are evaluated client side in browser. Evaluation is carefully designed with performance in mind but still it is possible to make recordings affecting client performance. Evaluation share target platform render resources and can affect overall platform rendering.

Context evaluate on each web page mutation to filter out instructions irrelevant for the current state. After context filtering, the targets are evaluated using highly efficient css selectors for supported targets or less performing custom selects by fall back xpath based evaluation.

Recording a large amount of instructions on the same app state using complex xpaths (yellow targets) will affect overall performance for that app state and should be avoided.

Instead use as much app state and green targets as possible.

Exercise 7 - Anchor points

  1. Create an instruction on the “My Desk” → “New Docs” tab

    1. Select the left anchor point while selecting (target the small grey circles at the edge of selection hitbox)

    2. Disable the target state in case your tab is active

    3. Add a “Title”

    4. Click “SAVE“

  2. See the callout position

  3. Collapse the left category menu and see what happens

  4. Toggle left category a few times and see what happens

  5. Edit and use the select to try out different positions

Exercise 8 - Tags

  1. From the “AUTHOR” panel tab create a new guide

  2. Assign a new tag by typing

  3. Go to “LIGHT MY WAY” user panel

  4. Click the tag label icon (should be a number next to it)

  5. Try how different combination will affect the guides listed under “ALL GUIDES”

  6. End with all tags deselected

Exercise 9 - Colours

  1. Guide colours

    1. Edit the “Create Part” guide

    2. Select a colour

    3. Go to “LIGHT MY WAY” panel “ALL GUIDES“ to see the colours in the full guide list

    4. Note the colour of all the guide callouts

  2. Specific instruction colours

    1. Find and edit the “Click OK” instruction in “Create Part” guide

    2. Expand options and select a different colour

    3. Click “SAVE”

    4. Execute the “Create Part” guide as an end user in “LIGHT MY WAY” panel and see the effects

    5. In “AUTHOR” panel expand “Create Part” and find the colour of “Click OK“

Exercise 10 - Finding the right guide

  1. As a user in “LIGHT MY WAY” panel execute the full “Create Part” guide so that you are in context of a newly created part

  2. Create guide “Change Process“, leave the description empty

  3. Create one instruction

    1. Give it some relevant text (see screenshot for example)

    2. Include default app states type and state

    3. “SAVE“

  4. Go to My Desk (home), the guide should be unavailable

  5. In “LIGHT MY WAY” panel “ALL GUIDES” search for a key word from the instruction description and find your guide

    1. Note that it is very hard to understand why that key word was matched and also from where it is available

  6. Edit the guide and add some long and rich description including the keyword. End with describing that the guide is available in context of Parts.

  7. Go back to the “LIGHT MY WAY” tab and see to results. Take a moment an reflect on what you think would be a good level to make users find relevant guides and know where to start?

 

Exercise 11 - Callout types

  1. Go to My Desk (home)

  2. Activate “Projects” tab

  3. Create a new guide

  4. Create a callout targeting the top bar search field with anchor position top

    1. Activate “App states” → “Tab: Projects“

    2. Expand “Options” and select “Instruction Type: Global Info” & “Colour: Red“

    3. “SAVE”

  5. Go to “LIGHT MY WAY” panel and activate the guide

  6. Toggle “Project” tab

  7. Take a moment and think about one use case when global info could be useful

 

Exercise 12 - Clone

  1. X

 

Exercise 13 - Chapters

  1. X

 

Exercise 14 - Performance

  1. X

 

Mastering guide creation

This is your final test. Do you remember your training well enough to record by heart?

Exercise 13 - Authoring by heart

  1. (Optional) Recreate the full Create Part guide (all previous exercises) by heart. Can you do it without looking at the steps?

  2. (Optional) Create your own guide from scratch. Maybe base it on a previous customer experience?

 

 

Related content

TECHNIA CONFIDENTIAL