[design needed] integrate how-to guidelines to create how-to form

[iSCJT]

Precious plastic to provide suggested design for discussion.

[iSCJT]

@sigolenej just on a call with @benfurber, he's happy to look at the design with you and @thisismattia with a view to implementing some changes.

[thisismattia]

Hey @iSCJT nice one. Hey @benfurber happy to have you to look into this as I am a little busy this week. Would you like to propose a few ways forward?

@sigolenej can we forward @benfurber some info to give him visibility over this issue and our requirements?

[sigolenej]

Hey @benfurber ! We wish to provide more information and support to the human who is creating his HT. This info is currently available in the guidelines, which means the human would need to have the 2 pages open side by side: https://community.preciousplastic.com/academy/create/howto

We believe that it will help humans to write better HTs and know what to include to have the guidelines "more integrated" to the form.

---

As you can see in the guidelines, the recommendations and expected attached files will vary from HT category (machines won't need the same docs as moulds).

A way to do this, could be: based on the category selected, a short description of what is expected is be added below the title & the typing block. Currently, the recommendation is in the typing block, which disappears when you start typing... I'll let Mattia do his magic when it comes to the design part :)

But in short, the goal would be to have the vital info we currently have the guidelines, integrated in the HT steps, without creating too much clutter, making things too complicated for humans or scaring him away.

Hope this help you to better understand our issue & what we would like to reach !

[benfurber]

Hey @thisismattia and @sigolenej.

I've played around with a few ideas. Viewable here.

1. To ensure a clear feel for the user, I think it's time to remove the sidebar so that the form can be single column.
2. That means moving the draft/publish buttons - I'd suggest the title header as show. With a nice to have then making the header sticky.
3. Then I played around with a bunch of basic field+guidance layouts. Personally I'd suggest the first or third. I think putting the guidance on the right means most users will never even notice it. But happy to go with the consenus.

What do you prefer as a next step? Written feedback here? Quick call? Happy to do whatever.

[benfurber]

Oh a point I forgot. Once I have guidance on the field layout you'd like, I'll finish a partial form mock-up including a design of the steps.

[thisismattia]

Hey @benfurber thanks for taking the time.

I like the yellow box, very informative.

We usually try to keep the designs as simple as possible with very strict grids and layout not to overwhelm the user and keep hierarchy. Your sketch seems to be using very complex grids with many areas of focus that might be overwhelming for users. I would try to keep it cleaner/simpler if possible.

If you can try to adjust the design to something more symmetric and organized?

[benfurber]

Thanks @thisismattia, good feedback.

I've added a v2 to the same doc

1. I think I was doing some random centering as I was finding the full 1200px width too much so I've very deliberately shrunk that to 1100, I'd happily go to 1000 to be honest - so let me know what you think about that.

2. I think the clearer makes me more confident that it should be option two or three. Three is simpler, but I think two makes it more likely to be read.

3. I've also suggested a tweak to the images/link for a step - to make it clear what's required (one or the other). Though I don't think the wording I used is right.

4. Also, are you happy with the save buttons being in the header?

[thisismattia]

Hey @benfurber thanks for the input. I've added a few comments on figma. Generally I'd say we need not to drastically redesign the whole page, we simply need to enhance the page with guidelines in the correct place.

This being said the yellow boxes you using on figma could be a good design solution. I would propose to try adding them to the current design of the how-to and see the resulting UX.

We would then also need to investigate with core dev team if it is even possible or good enough roi to develop different iterations per "category". Was this agreed @sigolenej ?

[benfurber]

I've added three v3 versions that make less changes to the overall layout. And responded to the comments on figma.

I'm happy to implement just adding the extra element to the page, but I really think it's cramping it, for exactly the reason you highlight @thisismattia about ensuring it isn't overwhelming.

Some other ideas we could look at:

1. Only showing the guidance to first time publishers (or first three or whatever).
2. Adding a toogle option to the page to hide/show all the guidance.
3. Doing both. Toogle defaults to show for first time publishers, defaults to hide for return publishers

Not that much extra work to add the personalised guidance for the steps based on the category selected - shown in the v3 suggestions.

[sigolenej]

To reply to Mattia tag, I indeed believe (but there is no market data that proves this need) that it could be beneficial to have a more detailed step by tep based on the HT category we are in.

Would this be doable @benfurber ? (+ added a comment on the figma) With this new design, we would no longer have the "flowing box" following you while you move down the HT correct?

If we were to have the proposed option 2), where would you image the possibility to show or not the guidance?

Thanks for these ideas @benfurber :)

[thisismattia]

Thanks everyone for your inputs ♥️ @benfurber i really liked elements of your designs and included in this further proposal.

I think the yellow box is very useful to draw user attention/focus. This being said I also believe it might be too much to have one of those boxes for each user input field. Having too many would probably result in the opposite outcome, user skimming by and not reading. In this design I propose to have 1 yellow box for category and 1 for download file as they're the key entries where people need to know what to do.

There I also propose to add 2 additional documents that go more in details on how to create a machine or mould how-to.

If people agree on this direction we could design instances for the other categories too

[benfurber]

Nice. Makes sense to me.

[benfurber]

Later in the week I'll get started on the main feature. Whenever it's ready, changing the copy to include the extra linked guidance is zero effort.

[davehakkens]

Hey just seeing this now, looks nice. But how will this be configured with other instances @benfurber? This copy is very specific for one instance (Precious Plastic) + specific for certain categories. Worried that this depth of customization will clutter the codebase for others.

And @thisismattia would not use the term 'commons'. This isnt introduced anywhere yet. Better to do it properly all at once if we decide to go for it.

[thisismattia]

Yep sorry legacy error from the design file. I mean how-to of course.

[benfurber]

The solution I've drafted will match the exact label of a category with the extra guidance notes in a coded text file. If there isn't an exact match; nothing will be displayed. The advantage of this is that all the text for the form is kept in the same place and is simple for engineers to update. Problem is that then it's content engineers have to manage instead of admins plus the edge case of if multiple instances want the same category label.

A more robust approach that could be tried would be to add extra fields within the admin section for categories. A lot more work though.

[sigolenej]

Hey @benfurber following up on this item, where do we stand on it ? :)

[davehakkens]

Thanks for the explanation @benfurber and follow up @sigolenej, I've asked @thisislawatts (long term maintainer) to bring his judgement on the codebase complexcity. This week he is getting back from holiday and will have a look on it in the coming days.

[benfurber]

Regardless of the technical approach, is the copy ready @sigolenej?

[benfurber]

@thisislawatts I've rebased #2714 to current master.

[thisislawatts]

Great thanks @benfurber 🙏🏻 That makes the diff much easier to reason with ✨

[thisislawatts]

question: For @ONEARMY/design, do we need really the new visual style; yellow background, dashed outline, that we have added here for the How-tos in the moulds category… block?

We already have two message styles used elsewhere to annotate forms. The screen grab attached shows the Your map pin section which for my user context contains:

• In order to… an important block related to editorial standards, this seems to align with the category messaging.
• You can click on the map less important helper text.

[benfurber]

Happy to change the design, etc. But I wonder if that would be better to update the map guidance in line with whatever design approach is finalised for this issue.

A couple of reasons:

1. I don't think info/guidance should be a warning/error colour.
2. I'm not sure the postioning of the guidance in blue (below the interactive element) is effect.

[thisislawatts]

Sounds good @benfurber, lets wait for some direction here from the Design folks.

Regardless of the exact visual implementation, I strongly believe that we don't need 3 distinct visual styles. Where possible we should be iteratively strengthening the visual cohesion of the Platform.

[thisismattia]

Hey @thisislawatts thanks for this. Was actually peripherally thinking about this in the back of my mind. Indeed would be great to use existing components. What component is the map message above?

This being said I believe we need a "info text" component that doesn't look so scary like red on white. Potentially @benfurber yellow design could be used for that as it feels more friendly. I would then transform the map message into yellow as realistically I am not sure it needs to be red.

[thisislawatts]

@thisismattia, currently the map message is a custom component, although worth noting we use the same style elsewhere on the Profile Settings page.

It would be great to move all of these too a common style.

My personal opinion is that Yellow places higher emphasis on informational text than necessary and I read the messages as warnings, but design can be a subjective medium so defer to @ONEARMY/design here.

[thisismattia]

Heyo @thisislawatts that's what I thought. Indeed yellow or red are too screamy for info components. The above design from the screenshot seems more appropriate.

Looking at storybook seems like you guys got this already figured it out?

Imo both map message and HT guidelines could live within the alert>information component.

[thisislawatts]

@thisismattia that was me doing some tidying up, I figure that the existing messages were of an informational tone, so figured I would get them to the user the Alert component with the information variant. Then any styling changes we make as part of this issue would be rolled out to them as well :)

[thisismattia]

Hey @thisislawatts sweet. Makes sense to me.

@benfurber should we then move forward with the above ux and content but applying the "Alert component with the information variant"?

[benfurber]

Hey all,

Yes very happy to finish this off now and thanks for linking me up with the component library (I hadn't been putting two and two together).

To double check. Are we staying we should: a) Change the current 'Alert component with the information variant' to yellow, or b) Use the current 'Alert component with the information variant' as blue*?

• = Adding a long form version like the failure error I can see on storybook

[thisismattia]

Hey @benfurber it is my understanding b) is the way forward we agree. Red or yellow seem a bit too screamy. Which means keep the 'Alert component with the information variant' as is and turn all info messages into it, including the original topic for this issue.

Thanks man!

[benfurber]

Cool. On it.

Do I have all the copy I need for each of the categories?

[thisismattia]

I believe you can use those ones for now https://community.preciousplastic.com/academy/create/howto

Let me know if you need any further direction

[onearmy-bot]

:tada: This issue has been resolved in version 1.100.0 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket: