How might we better structure #howto?

Site Feedback
#1

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 Docs - Discourse for Teams | Support

image
image1380×884 69.8 KB

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:

12 Likes
#3

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?).

5 Likes
#5
Start Contrib Config
discourse-new-user-guide
administrative-bulk-operations
install-plugins-in-discourse
beginners-guide-to-creating-discourse-plugins-part-1
setting-up-file-and-image-uploads-to-s3
using-object-storage-for-uploads-s3-clones
adding-an-offline-page-when-rebuilding
tags-category-restrictions-tag-groups-relationships
description-of-various-user-states-in-discourse-admin-moderator-staff-developer-other
beginners-guide-to-install-discourse-on-ubuntu-for-development
beginners-guide-to-install-discourse-for-development-using-docker
customize-all-text-in-discourse
how-to-use-discourse-safe-mode
how-to-create-polls

There are so many :sweat_smile:

10 Likes
#6

Looks like I was wrong! Thanks. :slight_smile:

6 Likes
#7

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
#12

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:

Start Setup Adv. Setup Contrib Config Adv. Config
DiscourseConnect - Official Single-Sign-On for Discourse (sso)
Configuring Facebook login for Discourse
Multisite configuration with Docker
Sending Bulk User Invites
Set up Reply via Email Support ✉
Configure automatic backups for Discourse
Move your Discourse Instance to a Different Server
Enable a CDN for your Discourse
Configuring GitHub login for Discourse
Advanced Setup Only: Allowing SSL / HTTPS for your Discourse Docker setup
Invite individual users to a group
Embedding Discourse Comments via Javascript
Configuring Google login for Discourse
Install Plugins in Discourse
Adding an offline page when rebuilding
Configuring Twitter login (and rich embeds) for Discourse
Troubleshooting email on a new Discourse install
Configure a firewall for Discourse
Beginners Guide to Install Discourse on Ubuntu for Development
Change the domain name or rename my Discourse?

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

8 Likes
#14

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
#15

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
#16

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
#17

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
#18

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
#19

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:

image
image1125×1327 169 KB

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

2 Likes
#20

This post was flagged by the community and is temporarily hidden.

#21

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
#22

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
#23

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
#24

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
#25

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
#26

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
#27

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