How might we better structure #howto?

We have a whole lot of guides, sometimes @dax or @jomaxro shares a howto guide I didn’t know existed and I am wowed!

I have also found this to be the case for a lot of new users and community managers on Discourse here on Meta. So in looking to solve this, @justin came up with an awesome idea to group our howtos and give everyone a better launchpad to start from and hopefully end up with something similar to https://support.teams.discourse.com/docs

I am currently looking at 3 groupings:

  • Getting Started
  • Contributing (including our plugin/theme tutorials and guides)
  • Configuring

Which of the howto fit into which groups for you?

I’d love to hear your ideas :smiley::heart:

13 Likes

I don’t think you’ll get any responses here because there is no motivation for people to take on this work.

We either need to assign it to our team or we need to find a way to make it simple (tags maybe?).

6 Likes

There are so many :sweat_smile:

11 Likes

Looks like I was wrong! Thanks. :slight_smile:

7 Likes

Haha yes there are! Ideally if we could land at 6-12 howtos per category, that would be great. We’re not looking to categorize them all but just the best that folks may be looking for.

@osioke – one way to approach this is look for the most viewed howtos that correlate with these categories and pick the top 6-12 most viewed to tag as such. Would be an easy starting point combined with @Benjamin_D’s suggestions here!

The beauty of tags is we can easily edit them as we go, too.

7 Likes

Thank you for sharing this @Benjamin_D! One of the things I was struggling with was how to present and how to think about the structure, your table here helps a lot.

I am now looking to expand the grouping from 3 to 6:

  • Getting Started
  • Setup
  • Advanced Setup
  • Contributing
  • Configuring
  • Advanced Configuring

And like @justin shared, looking at the most viewed, I have the first 20:

What do we think?

This would end up being a big change, so permit me to call in the big guns and cc: @trust_level_3

9 Likes

Hmm, the login setup articles could probably carry a category all on their own, and it’s a subset of Getting Started because it’s one of the first things you want to do on a new site, if you want to do it at all.

7 Likes

I not sure multisite needs to be mentioned here :thinking: or maybe the adv config group could come with a warning, search meta ! For instance this post is very useful pros-and-cons-of-a-multisite-installation .

About the Sending Bulk User Invites, I tend now to use multiple-use-invite-links, perhaps mention both topics?

I think I’d set Set up Reply via Email Support :email: in the advanced setup group (since I still haven’t done it :see_no_evil:) and straightforward-direct-delivery-incoming-mail is probably worth mentioning but maybe in the adv. config group, because … well… email :scream: .

The contrib group seems a bit empty, perhaps something theme or component related would be nice, such as developer-s-guide-to-discourse-themes , designers-guide-to-discourse-themes and beginners-guide-to-using-theme-creator-and-theme-cli-to-start-building-a-discourse-theme

3 Likes

True true, the list is based of the top 20 most viewed, and I shared that to show my thinking around the arrangement. It is in no way the final list, I should have been a little clearer :sweat_smile:

3 Likes

I’d like to see administration or operations as a category for ongoing admin and moderation activities. It doesn’t fit with setup/configuration and isn’t development/documentation (contributing).

2 Likes

I assume the Discourse for Teams doc site is using Discourse for all the docs. The issue with that for a howto site for Discourse where anyone from the community could participate is versioning and keeping track of everything. I’m sure using discourse for this would be the preferred method but may I suggest maybe a hugo site or a Jekyll site and have the documents be files in a github that anyone can make PRs to. If you don’t like either of those, there’s many more github repo doc systems that come in many flavors.

1 Like

Oh, versioning works pretty well on Discourse, pretty well even. And combine that with category access security, and you have something we are proud of using :wink:

That sounds about right, can you share some posts that would fit in there?

2 Likes

FWIW, I’ve been slowly working on cleaning up #howto:sysadmin, checking that each one is up to date and relavent and then having them moved to auto-delete-posts-after for them. It looks like most of those have been categorized here as advanced config.

7 Likes

Fully agree. Multisite is a super super advanced configuration and is not something we support on Meta much.

It sure is. Discourse + the Docs plugin + some extra customizations. Using Discourse is our preference for this, but I do see the benefits of using a wiki/SSG site also.

Thanks a boatload for doing this :heart:

6 Likes

It would be great if the “less supported” topics could go into their own clearly marked category.

There does seem to be a current mindset that if it’s written here then support is in some way owed.

It also makes it easier to advocate for users to test prior to upgrading, because such features are usually more fragile or less widely tested between releases.

image

Subfolder, multisite, tertiary categories would all fall into this bucket, right?

6 Likes

I think that multisite is pretty much “supported” but it’s expected that if you go down that road you know that more is expected of you (e.g., you need to think about what rebuild app means in various contexts). I’d say that it’s “advanced”, but not “super super advanced”.

Agreed that teriary categories and subfolder are “super super advanced”.

4 Likes

Maybe I’m more thinking about multisite with Let’s Encrypt, that has broken repeatedly over the years and sometimes the updated documentation has taken weeks or months to emerge.

4 Likes

Ahh. Yes. I do think that’s probably pretty stable now (I think the last change had to do with how redirects were handled in nginx), and I do have a Multisite Configuration with Let's Encrypt and no reverse proxy - Documentation - Literate Computing Support that I mean to post here Real Soon Now (it was December 2, 2020 that I wrote and last tested it). But multisite is definitely you’re-mostly-on-your-own. I don’t think it even makes sense unless you have at least 3 (maybe 10?) sites, since it seems that most people who think they want it are trying to get by on a single 1GB droplet.

4 Likes

What I would find most helpful is if you don’t put more effort into structuring the category (how-to) as such, but rather give a better structure to the Docs.

I really appreciate if the forum is just fluid for users to post. I think for that it’s central you have good top level categories and users post in the right one of these. But when sub-categories get complex, when it becomes important for users to post in the right sub-category or in which sub-category to look for stuff, I find that somewhat disruptive.

Right now you practically just mirror the forum set-up on the docs:
Screenshot from 2021-02-25 22-21-09

Why not have staff use some staff-only tags to curate and structure the docs, like ‘docs-getting-started’, ‘docs-setup’ - with content from anywhere on the forum? Then you could set up a Docs page that is more than just a mirror of the forum, but has a properly curated table of contents, like:

Docs
+Getting Started
+Setup
+Advanced Setup
+Contributing
+Configuring
+Advanced Configuring

2 Likes

That’s actually the idea here, @nolo! We’re planning to create some ways to easily filter by these types of how-tos, but still retain the filters that already exist in the Docs plugin. Organizing these how-tos into specific tags is the first place to start.

6 Likes