How shall we edit and set the order of topics in the Handbook?

When the user clicks 'Handbook" they are taken user to a list of topics sorted by date of revision rather than following any judgement about priorities or thematic grouping. Perhaps this is work the @community team could consider?

FWIW, I also find the terms Handbook and Rulebook confusing. Perhaps one way to lessen the issue would be for the Rulebook to appear near the top of the list.

1 Like

As an admin, you can browse the topic sorting options for the Handbook category here: Resonate Community Forum

The exact sequence of topics cannot be sorted manually afaik, but perhaps we could find a better sort option than most recently updated. I haven’t identified a need for why though because my expectation is that those who need to find information in the handbook will find it primarily by:

  • using the Search bar in Docs view
  • using the forum’s default search function, which is set to prioritize results from the Handbook
  • going to a subcategory such as Roles or Policy
  • clicking the tag in the handbook sidebar that represents their needs: #for-listeners #for-artists etc, thus sorting the topics that way

Once sorted, there aren’t many topics to scroll through, so further sorting options has seemed redundant. The implication of the Handbook is that few people will ever need to read all of its topics. It’s more of a wiki than a “book”.

If necessary, we could pin key topics such as the Rulebook/bylaws in its respective subcategory or the main Handbook category. This would raise their visibility.

It makes more sense to me to change the name of the the Rulebook-related topic to “Resonate Bylaws” than it does to me to change the name of the Handbook. “Rulebook” seems to be a term specific to Irish co-op law and it is probably not clear to many folks that the “Rulebook” even is the bylaws.

As an Admin, I’d like buy-in from the @community with the consideration of the @executive. That’s why I’ve posted here.

Perhaps they could be numbered?

As a user I am identifying that need. I think the Rulebook is a primary document for the organization and should go at or near the top of the list of any introductory documents.

One problem with this assumption is that it depends on the user knowing what search term to use to find their answer.

Another problem is that in many of our categories there may be many ‘answers’ from a search that do not actually lead to useful answers. (This has been my experience.)

By organizing topics thematically with some intuitive editorial insight or an eye toward an educational sequence I believe we can dramatically improve the user experience and foster good co-operative ‘citizenship’.

1 Like

Btw, these are the people you are notifying when you tag the @community usergroup: Community - Resonate Community Forum

I offered a solution to this. The topic can be pinned.

If you’d like to explore further solutions to your questions, Discourse Meta will have more information.

If you’d like to propose a numbered sequence for the topics in each category, go for it. Due to the nested structure of the Handbook’s organization, I don’t believe this will be possible, without at least one category having its numbers shuffled out of order.

2 Likes

I’m thinking the solution (ordering Forum resources by editorial and educational insight) is one that would come from the engagement of users of various needs, temperaments and learning styles.

I engaged here to initiate that pluralism of input.

Thank you for sharing, @Hakanto.

1 Like

Maybe the Handbook should be a Wiki not a category? Or a one topic category that is actually a wiki?

1 Like

You could poll forum users to confirm the Handbook isn’t working for them before a redesign would be undertaken. And poll how high priority they feel it relative to other things we could be improving.

I’m quite a tinkerer – always want to improve things – but with our tiny crew and low capacity I encourage being aligned on priorities before taking on new tasks.

I’m dwelling on the handbook because it is offered as the main resource for members to learn how to participate in the co-op. It is for this reason, I believe, that it has a very prominent location on the header-bar.

Right now its order has nothing to do with its content. It can only teach what a user already thinks they need to know.

If it was organized more like a handbook I think that would be a big win.

I understand that capacities are limited. I’m not making any demands here.

I’m making a suggestion that I think might make the work easier for all as more people find resources that help improve collective capacity.

If no one is able to move on this suggestion, or no one has the desire to, then life will go on as though no suggestion was made.

:grinning:

2 Likes

Example: https://handbook.hypha.coop/

As @Hakanto suggested above, it would probably be pretty easy to add numbering to the titles of each Handbook article. Hopefully there’s a way to have Discourse default sort the Handbook entries by title instead of last updated at. I was able to press Title to toggle sorting to that pretty easily (obviously not as ideal as being able to default it though if we opt for this approach).

Hypha’s docs are nice. It seems like what you may be proposing @richjensen is to make the Handbook more like our Resonate Docs website (or expand Resonate Docs to also contain these more general entries in the Co-Op - I could easily make two sections on the website one for tech and one for general handbook that users could access via the navigation bar at the top. It looks like I could potentially get the raw markdown for each handbook entry (https://assets-meta-cdck-prod-meta.s3.dualstack.us-west-1.amazonaws.com/original/3X/9/e/9ede9f848aafb9af5182721f9976de7cbcbbc841.pdf) and display them also on the Docs website in a certain order. They would still be editable from Discourse - drawback here would be if an edit is made or a handbook entry’s location is moved, we would need a dev to be messaged so they could run the re-import external markdown files and deploy script to update the live site (and if an entry’s location moves, update the code to import it from its new location). I’m hoping to dig into this and look into feasibility when I get the time. This approach would be good because it would still empower users to be able to update, but, a dev would need to be contacted to take the update live, which is a higher barrier of entry rather than just updating Discourse and letting everything live just here, so that’s mainly what concerns me.

I’m not sure how others feel, but I don’t think it would be the end of the world if you wanted to experiment with prepending each Handbook entry with a numeric that you think would be a good order to take new users through @richjensen. You could even draft a potential sequence you’re envisioning here in this thread and we can discuss further from there.

5 Likes

That looks pretty rad, Peter. Thanks for looking into it. I’m not against any of these improvements “in principle”, I hope that’s clear.

TLDR from me: The current forum design is good enough and we need to maintain it the way it was designed and reflect on that state of things before we start taking on new features.

I’m emphasizing the “How We Work” meta issue of task tracking, prioritization, and capacity. In the list of all current work tasks we could be doing, I encourage collective agreement - primarily among those who will be doing the work - about its priority.

For example, it appears that the Category Headers plugin has recently broken and no longer displays links correctly. Folks can see an example at the top of any main category page like Platform. This is something we’ve already installed – and now we have to maintain it. I don’t know how to fix it.

If I had to rate these potential Handbook improvements, I’d file them under “Would be nice”, not “Must have”. Until we’ve sorted out commitment to existing worker routines and “Must haves”, I don’t have confidence that my efforts on new features will be meaningful to myself or to users.

Broadly, I think there are many situations at Resonate where someone concludes that the car isn’t moving because its design was flawed, when the reality is that the car isn’t moving because it doesn’t have a driver or gas.

2 Likes

Perhaps this line of discussion belongs in a different thread?

@peterklingelhofer Thanks for the encouragement (and diligent research!)

If I pursue this I will likely choose to work within the auspices of the @community team in dialogue with the community sessions.

Co-op education, collective practice and plurality across technical and non-technical communities, specifically as these relate to Resonate, feel like central concerns and topic areas to work contributed in that space.

2 Likes