search

mattermost / docs

Mattermost documentation
https://docs.mattermost.com
BSD 3-Clause "New" or "Revised" License
211 stars 582 forks source link

Feature: Reformat data in the product feature breakdown table #7498

Closed TomerPacific closed 3 weeks ago

TomerPacific commented 1 month ago

Following the discussion from #7024, it was suggested that there could be a better way to structure and present the data shown in the product feature breakdown table.

This issue's purpose is to come up with different solutions to present the data and agree on the one that works.

TomerPacific commented 1 month ago

@cwarnermm - One suggestion I have in mind is to have a drop down that selects the product type (Web/Desktop/Mobile) and then show the different features for that product type. Another option (that could be part of the first suggestion), is to let the user select to see different features that are separated into the categories (messages/teams/etc.) Also, since most of the features are fully supported in Web & Desktop, there could be a way to just do the opposite of stating what is supported. Meaning, having a short description of saying that most features are supported in Web & Desktop and then saying what is not supported/partially supported in Mobile.

Let me know what you think.

cwarnermm commented 1 month ago

@TomerPacific - I really appreciate partnering with you on this challenge, and I like the way you're approaching this.

A drop-down approach would be incredible; however, this isn't something we've attempted to do before, so the learning curve may be steeper than expected. I'm open to it, but 0/5 on how much effort is needed to build something interactive like that onto a docs page.

The idea of reversing the details to focus on what's not supported per client is an interesting approach. We'd still need the full list of what is supported, but finding a way to identify, at a glance, what isn't per client would be highly valuable.

For next steps, it may be easier to draft out a desired end state via Google Docs or similar tooling that could be shared more broadly with more stakeholders, including our UX team, for feedback.

TomerPacific commented 1 month ago

@cwarnermm - I'll work on a Google document that outlines several approaches, with pros/cons for each one and share it here. I'll allow others to edit/comment so it will be an interactive document, which hopefully will lead us to an agreed upon solution.

Sound good?

Let me know who I should be sharing this document with.

cwarnermm commented 1 month ago

Sounds amazing! Thank you, @TomerPacific!!

cwarnermm commented 1 month ago

I'm thinking that we'll share the link to the GDoc in Mattermost discussion threads on the Community Server.

TomerPacific commented 1 month ago

@cwarnermm - Here is a link to the document. Which channel would be best to post this? DWG/Contributors? Or should I open a new thread?

cwarnermm commented 1 month ago

@TomerPacific - Let's share it in DWG; we'll invite UW and QA to share their thoughts.

cwarnermm commented 1 month ago

We received really great input from a number of stakeholders on best practices around table-based content in docs.

From that input, here's how I'd like to proceed with the table content on the https://docs.mattermost.com/about/faq-product.html docs page:

  1. Split out the table into page sections, each with its own H2 level section title, as follows:
    • Messages
    • Channels
    • Teams
    • Collaborative Playbooks
    • Calls
    • Integrations
    • Authentication
    • Additional Features (replacing "Other")

These section headers will display in the far right navigation for easy page-based navigation.

Each docs section will contain a table with the same 4 columns as what's published today: Feature, Web, Desktop, & Mobile.

Replace full support "x" indicators with green checkmarks, using the https://docs.mattermost.com/collaborate/collaborate-with-audio-video.html docs page as a code guide. The green checkmark is defined globally, so all that's needed is the shortform reference (as seen in the docs code). It's expected that the checkmark icons will align left and not centered when displayed on the page.

In cases where partial coverage is indicated (mobile only), replace the "o" with the text "Partial Support" for clarity.

Ensure each feature across all tables on the page is also a link to its respective docs topic. Flag any features whose associated docs page isn't known; @cwarnermm can help identify specific docs pages as needed. Ensure links are formatted as relative links rather than absolute links. Use the https://docs.mattermost.com/collaborate/collaborate-with-audio-video.html code as a guide for this syntax.

Once the single table is broken out into multiple tables across sections on the page, remove the Legend details.

Tip: I strongly recommend using https://www.tablesgenerator.com/text_tables to generate reStructuredText syntax for each table. This site makes short work of defining table text, including all necessary RST syntax, such as ** for bolding, and for link text.

TomerPacific commented 1 month ago

@cwarnermm - Do you have somewhere I can look or a mock I can see of what you want the page to look like? Which section should be before the other? Do you want Web first and then Desktop and Mobile? I'd really appreciate some clarifications.

cwarnermm commented 1 month ago

@TomerPacific - Use the same order as what's published now for both the sections and the features, please.

TomerPacific commented 1 month ago

@cwarnermm - Posting here a preview of revamping the table with the Messages section (the screenshot cuts the table):

mm

Let me know what you think and then I will be able to proceed with the rest of the sections.

cwarnermm commented 1 month ago

It's a thing of beauty, @TomerPacific! Looking forward to seeing your docs PR. Happy to help identify any link URLs needed too.

TomerPacific commented 1 month ago

@cwarnermm - Going over the features under the Messages section, this is what I found (those without a link mean that I was not able to find the documentation for it):

Could you help me in identifying the correct documentation links for the features I couldn't find?

I'm going to move on to other sections and hopefully, I'll fare better there.

Thanks

cwarnermm commented 1 month ago

Thanks, @TomerPacific!

I don't have a link to provide for the Search highlighting feature. I'll follow up with our product team to learn more.

TomerPacific commented 1 month ago

@cwarnermm - Thanks! Just went over the Channels section, I got this there:

cwarnermm commented 1 month ago

Thanks, @TomerPacific!!

For Archive members, let's change that to :ref: Deactivate members <configure/user-management-configuration-settings:activate or deactivate users>

For Leave channel, link it to :ref:<collaborate/join-leave-channels:leave a channel>

For Add members, link it to <collaborate/manage-channel-members:add members to a channel>

TomerPacific commented 1 month ago

@cwarnermm - I have gone over all the sections and below are my findings:

Teams

Collaborative Playbooks

Calls

Integrations

Authentication

Other

cwarnermm commented 4 weeks ago

@TomerPacific - Really great work here!

You can safely leave the following features as-is without a link. I'll follow up with our Product Team to clarify the intention of the following features given that we can't match them directly to docs pages:

TomerPacific commented 4 weeks ago

@cwarnermm - I have opened a draft PR and I would like to ask for your assistance for the links in the Authentication section. For some reason, the format I am using there is not working. Can you help me understand what I am missing?