Revise Guidance on Write Plan page - updated

[stephaniesimms]

UX wireframes @JEK-III : http://h90c3m.axshare.com/#g=1&p=write_plan

• one guidance/comments portion per question, but refactoring the UI to be similar to the wireframe linked above and screenshot below
• Use a slider to switch between guidance and comments and create guidance tabs by organisation
• Related issue started as Revise Write Plan page #494 and continued in Finish Project Details page - including Guidance section #943

Additional notes from @briri (please confirm that I captured everything relevant):

• All guidance sections should be collapsed on page load or a new section is expanded
• If a guidance area was expanded and is still available to the user, it should remain expanded
• The current tab guidance/comments should remain active (e.g. if the user had the comments tab open and clicked on a different answer then the comments tab should remain open)

[briri]

Implemented according to screenshot above but using current tab color/styling except for the theme accordions within each guidance group. It seemed too cluttered when I first tried it with the normal accordion colors (grey background w/ white text) so I updated them to be white background w/ grey text:

The tabs display the GuidanceGroup name, so we will have to ensure that we curate our existing group names. I was going to use the Org abbreviation but that wouldn't work for orgs that have multiple guidance groups (e.g. Univ. of Edinburgh and Roslin Inst.)

[briri]

question for both @sjDCC and @stephaniesimms:

How should we differentiate between question level guidance and themed funder guidance? The first 'DCC' tab here contains the question level guidance (entered on the template edit page).

The second 'DCC' tab is themed guidance provided by the funder. Note that DCC is the template owner/funder in this example

We could always use a hard-coded value like 'Template' instead of the Org name for the first tab (assuming there is question level guidance available).

[briri]

spoke with @stephaniesimms and we think the bold org name above the tabs should be removed. Its a bit redundant since the user can see which tab they've selected.

@stephaniesimms proposes to curate the names of the guidance groups to prevent this duplicate tab name issue. We think DCC may be the only instance where the template owner also has themed guidance. Can you confirm that @sjDCC ?

She has also suggested adding the 'expand all /collapse all' links back to the themed guidance tabs

[briri]

Made the changes recommended by @stephaniesimms.
I also decided to limit the amount of text allowed when displaying the guidance group name to 15 characters to help keep the tabs from stacking like an accordion. We can adjust or remove this restriction if needed. I'll deploy it though so you can both do some testing.

[stephaniesimms]

just a note that I already curated the short names for Orgs, which we can use to display in the tabs (so Pitt, LLNL, Griffith, DOT). Org admins typically enter these themselves on the Org details page anyway. I'm liking what I see so far - we will both test more @briri - thanks.

[briri]

Thanks @stephaniesimms Just wanted to note that the names displayed are guidance group names for all but the first tab (these display themed guidance). The first tab uses the org name (displays template annotations).

[sjDCC]

Hi @briri I fear the duplicate first entry is inevitable now with changes we made. It won't be restricted to DCC as most UK unis who've customised the tool have themed guidance.

Previously the guidance group could be set to apply to specific templates but now it applies to all by default. This means that if an institution has themed guidance AND annotations on their own templates, there will always be a duplication. The first entry will represent their template-specific annotations as Brian notes and the second will refer to any themed guidance.

One fix to this could be to implement a rule that themed guidance is never applied to the organisation's own templates. That should work as I think every template I've seen entered has specific guidance for each question. The concept of themes is really just a labour-saving device to apply guidance to all the funder templates and manage/update it more easily. This would also stop the DCC generic guidance being applied on the default template since that is owned by DCC and has guidance specific to each question.

[stephaniesimms]

@briri - per @sjDCC comments above can you implement a rule that themed guidance is never applied to an org's own templates? it sounds like that will alleviate the duplication problem, including for DCC/default template and DCC guidance.

[stephaniesimms]

i noted the following problems while testing:

• @briri I can click on different guidance tabs on the Write Plan page but i can only ever see the funder guidance attached to template - this appears to be a bug (maybe related to clicking on a tab makes the page jump to the top #996 ?)

Funder (in this case, CRUK) guidance visible regardless of which tab is selected

If no funder guidance avl for a question, then I cannot see any guidance when selecting tabs; the view is blank

• the logic of not applying themed guidance to an org's own templates doesn't quite pan out. it does alleviate the problem of duplicates. but e.g., when I use the Univ of Edinburgh template I'm presented with 3 options for subsets of UoE guidance (screenshot below). it's fine to exclude the first "Edinburgh" subset if that info is already presented in the template, but I may still want to see the "Roslin institute" or "Koala bear" guidance. When I tick these boxes, however, they aren't displayed on the Write Plan page. I'm assuming this is bc they're also excluded as belonging to UoE.

[briri]

yes, that may be related to #996.

As for the Roslin/Koala bear scenario, we can't do that accurately. All we have for comparison is the Org that owns the template and the Org that created the guidance group. We'd have no way of distinguishing which guidance groups to show and which to hide. We can either block all or none.

Another option ... we currently auto-select the template org in the guidance selection on the project details page and we do not allow the user to unselect it. We could allow it to be unselected. The template will always show guidance entered at the question level (aka annotations) regardless of user's selections here. checking/unchecking that box determines if themed guidance is available.

@sjDCC and @stephaniesimms what do you think of that option?

[sjDCC]

I'm struggling to understand the problem here so perhaps worth picking this up on the dev / Tues call.

Picking up on @stephaniesimms first problem, I think the issue is that all the guidance is appearing on the first tab now. It's not being separated across tabs by ownership anymore, hence every tab showing the same. Here's an example for NERC. The piece of guidance highlighted is the NERC guidance. All the others are DCC themed guidance and shouldn't display until the user clicks into tab 2.

The layout of the plan guidance configuration is misleading. @vyruss could you explain this on the next call please? The first selectable 'Edinburgh' option is the university-wide themed guidance, which is not a subset. The other two are optional subsets. We wanted to group/associate institutional level and subset guidance, hence introducing the "University of Edinburgh" org name as a top level. This is the org name rather than a guidance group name though, hence it being greyed out for selection. It's not the most intuitive so I'm sure we could present it better e.g. have "Edinburgh" guidance group as the top-level with subsets indented below?

Ticking 'Koala bear' or 'Roslin' should display them on the template so I think the new logic is perhaps blocking things here. The annotations (either from the template owner or from a customisation) will always display and can't be turned on/off by users is this configuration afaik. Or perhaps the customisation annotations turn off when the institution level guidance is deselected, and it's only the template owners own annotations per question that can never be removed?

@briri, in response to your 2 points:

1. The Roslin and Koala bear are coming in because the user selected 'Edinburgh' in the org dropdown when creating the plan. Optional subsets like these should always be deselected by default. It's only the institution level guidance that we'd apply in response to this selection. Since we said org themed guidance should be deselected for their own templates to avoid duplicates (i.e. annotations AND themed guidance presenting) we only need to deselect the org when the template owner and org from create plan wizard match.

2. We do allow the user to deselect the org mentioned when creating the plan. As noted above, the layout of the guidance configuration is misleading. The first option "Edinburgh" is not a subset. Deselecting this removes the org themed guidance (and perhaps customisations on funder templates?)

[vyruss]

@sjDCC while I agree that it is not intuitive right now, having "Edinburgh" as the top level guidance in this type of tree view presents the problem that ticking a top level box is expected to tick the sub-entries too (which makes no sense here).

• Instead of implementing something that would untick Edinburgh (top-level) when you select an optional subset, I would recommend that we rename "Edinburgh" (the guidance group name) to University of Edinburgh General Guidance (or something). I believe that if the top-level (non-optional) guidance has no name, the Organisation's name is substituted in its place.

[stephaniesimms]

after more testing the same issues appear to persist @briri :

• default/DCC guidance appears in the main list on Project Details page but is not ticked. This should be selected by default.
• now I only see the top-level Univ of Edinburgh guidance on the Project Details page (screenshot 1), ticked by default. I have to click the link to open the full list to find any sub-groups (e.g. Roslin Institute) and it's not clear that this is a sub-group or associated in any way with Univ of Edinburgh. Desired behavior is to present the full set of Univ of Edinburgh and any sub-groups on the main Project Details page, with separate tickboxes and with the subgroups indented below the main UoE guidance. Only the UoE guidance should be checked by default and the User can opt to select any sub-groups instead or in addition to it.
• these items should also appear in the full list when a user clicks the link. currently the main Univ of Edinburgh group does not appear in the list, only Roslin Institute.
• on the display side, when writing the plan the guidance selections are still stacked together in each tab. they should be separated into their individual tabs (screenshots 2-3)

1 - DCC and Univ of Edinburgh guidance should be selected by default. Sub-groups for Univ of Edinburgh should appear in this list, indented below and unselected (e.g., Roslin Institute).

2 - When I navigate to the write plan page the first tab should be selected and only the first two pieces of themed guidance should appear there. The second entry for "Data Volume" belongs to the Roslin Institute and should appear under that tab when I select it.

3 - Currently all three pieces of guidance appear in both tabs. If I click the link to expand all, only the top two accordions open in either tab.

[stephaniesimms]

after more testing most of the same issues appear to persist @briri - guidance selection issues noted in related issue #943

• the guidance is still stacked in a single column on the write plan page. if I click a tab it jumps down the column to the top of that group.

[briri]

Hmm. it doesn't seem to have deployed the changes properly. I just redeployed @stephaniesimms and the fixes for this one appear to be in place. Apologies for the confusion

[stephaniesimms]

yes they do, thanks @briri - after more testing i see some minor issues that may be unrelated to this one. let me know if i should create separate tickets:

• the Org names in the guidance selection list appear with only the first word capitalized (it should be however they appear in the db, most have all words caps).
• for the tabs on the write plan page we should use just the Org short/abbreviated name. currently it's using the full guidance group name "Glasgow Uni guidance"
• only for guidance subgroups we should use the full name, e.g. "Roslin Institute"
• clicking the tabs still causes the focus to jump to the top of the page, but this seems to be covered in clicking on a tab makes the page jump to the top #996

[briri]

Thanks @stephaniesimms its really difficult to use the org short name/abbreviation in these tabs. There really isn't a good or clear distinction between normal guidance groups and optional subsets at least not within the code. If you look at the UoE guidance on roadmap-stg, 'Edinburgh' guidance is not a subset but 'Roslin' is.
Right now if an Org only has one guidance group we show the org name/abbreviation in the guidance selection list on the edit profiles page. If there are multiples we show each guidance group under the org name whether they are subsets or not. I'm wondering now if the logic behind these are flawed/incorrect. If so I think this is due in a large part to how we want to display names on the write plan page.

What if for example UoE had 2 non-subset guidance groups, 'Edinburgh - Old Town' and 'Edinburgh - New Town' as well as the 'Roslin' subset? How would they be displayed on the list of choices on the project details page?

• University of Edinburgh
  • Edinburgh - Old Town
  • Edinburgh - New Town
  • Roslin

Right now there is now way to tie Roslin to the Edinburgh guidance group (meaning 'Roslin' is a subset of 'Edinburgh'). There's no real hierarchy to guidance groups. If that's the case do we really only ever want to allow one top level guidance group per Org?

[stephaniesimms]

thanks for the explanation and reflections @briri . these are questions for @sjDCC since I'm not familiar with guidance subgroups beyond liking the concept.

[sjDCC]

Hi @briri I suggest we speak about guidance groups on the call today to clarify this, but will give a bit of explanation here for reference too.

Subset guidance groups should always be clearly linked to the org. The only way they can be created is via the 'guidance' page on the org-admin interface, checking the box to indicate that this is an optional subset. They must inherit the creating org affiliation in the code.

There should only be one main guidance group at the institutional level. We're now creating this automatically when the org is created. I assume the logic prevents there being more than one top-level guidance group but it would be good to confirm this.

The logic of the guidance configuration display is flawed as organisation-wide and subset guidance are shown on the same level. Only the organisation-wide guidance should be selected by default though (based on the org picked in the 'create plan' wizard) - optional, subset guidance is always deselected and only displayed if the user specifically chooses it.

Ideally there would be a box for Edinburgh at the same level as 'DCC' here (screengrab above) but there is some reason why we can't. Perhaps its to do with inheritance, and if we auto-selected Edinburgh at this level then all the subsets would also be chosen? Or perhaps its to do with how we're representing them in the code that there isn't a proper hierarchy of institution-wide guidance group vs subsets.

[vyruss]

OK after a discussion I had with @sjDCC we think it's best to go with:

• Digital Curation Centre
• University of Edinburgh
  • Roslin Institute

(indented optional guidance - but with no tree-type connector)

[briri]

Fixed issue with capitalization (see screenshot above for DCC line).

Going to leave the optional subset as is for MVP. Although its not ideal its the safest approach to display all of the guidance groups under the org (as in the screenshot above) rather than adding code in to force a hierarchy onto data that may or may not adhere to it. I propose we truly fix the issue after MVP (update the guidances page so that there can be only one top level group per org).

[stephaniesimms]

created new post MVP issue #1166 to resolve guidance subgroup issue. bug related to not being able to deselect guidance noted in #943 .

issue w/capitalization fixed. closing this one.

[sjDCC]

Sounds good. Removing from board