Welcome to Codidact Meta!
Codidact Meta is the meta-discussion site for the Codidact community network and the Codidact software. Whether you have bug reports or feature requests, support questions or rule discussions that touch the whole network – this is the site for you.
Help page: call for improvement suggestions
At the top right of each page is a link to Help.
If you want a specific help article to be edited or added, please raise that on your community specific Meta so that a moderator can make those changes for you. This question is instead about changes that moderators cannot currently make.
If there is something about the help system that you would like to be improved that moderators do not currently have access to change, please mention it in an answer. I recommend making a single suggestion per answer, so that voting can show which changes there is more community demand for, so that they can be implemented in priority order.
Identify and protect key slugs Some help topics are linked to from within the software. For example, the search page …
5d ago
Clearer distinction between Guidance and Site Info (Even if we make the main page directly editable as suggested in a …
5d ago
The presentation you show is not optimized for what people should be coming to Help for. The help topics are also in a …
5d ago
Ordering within category Topics can be ordered within a category if you edit them to add sequence numbers. In the ab …
5d ago
4 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
Ordering within category
Topics can be ordered within a category if you edit them to add sequence numbers. In the absence of explicit sequencing, they appear to be alphabetical by title.
For the "default" (baked-in) topics, we should seed these with sequence numbers so they come out in a logical order. When we do this, leave gaps between those numbers to make it easier for communities to insert new entries. We should then apply this sequencing to every community that hasn't locally modified this already.
The benefits would be a more logical ordering for new instances and consistency across communities on our network. Nobody should have to hand-edit sequence info into every topic on every community on our network.
2 comment threads
Identify and protect key slugs
Some help topics are linked to from within the software. For example, the search page links to the topic for advanced search, formatting help is linked when creating a post, and I think there's a warning about images without "alt" text that links to that topic. I think there are a couple more cases.
Communities can edit their help, including deleting or refactoring topics. What happens if a community changes or removes one of these special pages, so that those built-in links are no longer meaningful? At the moment, people editing help don't see any cautions about this and we don't protect those URL slugs from being changed. Can we prevent accidental breakage?
We'll need to compile a list of help pages that have these extra dependencies. We should make that information available (somehow), and perhaps we should "lock" those URL slugs and prevent those pages from being deleted. A message could be shown when editing, to alert editors to the dependencies.
I don't think we should lock these pages down entirely. Communities have already extended the original formatting help, for example. We want communities to be able to adjust help in the ways that meet their own needs -- we just want to avoid accidentally breaking dependencies.
Clearer distinction between Guidance and Site Info
(Even if we make the main page directly editable as suggested in another answer, there'll be a default for communities that don't want to rework things themselves. This suggestion applies to that default, or to the current way of doing things if we don't implement that suggestion.)
The "Guidance" and "Site Information" categories don't seem to have a meaningful distinction any more. Formatting help is in the latter but accessibility tips are in the former. Some topics in the latter are more "information" than "guidance", like how answer scoring and ordering works, but the voting topic is in the other category. I think there was a clearer information design at the beginning but that things have become muddled.
I'm not sure how these two sets of topics should be organized, but I don't think the existing categories are the right answer. Do we want a "Formatting" category (three current topics, plus more for communities that use MathJax or code syntax highlighting)? Do we need to refactor some individual topics?
0 comment threads
The presentation you show is not optimized for what people should be coming to Help for. The help topics are also in a rather arbitrary hierarchy, and not showing the relative importance or order that things should be read by a new user.
For example, most of the Policy stuff should be reference at the bottom, not main Help information.
To fix this, the whole Help should be one single page that site moderators can edit. Codidact can provide a template for new sites, or URLs for links to standard Codidact articles, like most of the Policy stuff.
The advantage of a fully editable page is that Codidact won't dictate an overall presentation, and therefore doesn't have to deal with the associated arguments of what should go where, and the work of maintaining it. Codidact can still provide a template for new sites, which can be left in place when the site admins don't want to bother.
Back when the Electrical Engineering site was new, I wrote a bunch of help pages aimed mostly at telling new users what they needed to know from their perspective. Unfortunately, since then Codidact has imposed much distracting drivel (from the point of view a new user) around what I wrote. The ever-confusing issue of what is Codidact versus the particular site you are on is not clear, and the part I need new users to see is buried where they will probably give up before reading it.
Effective teaching starts with the learner's context in mind, then presenting new information in a hierarchical form always relevant to the existing context that is slowly being built. The current Codidact help totally fails in that regard.
The whole presentation makes no sense at a high level. I'd be willing to put the effort into fixing it, but can't change the parts that really need to be fixed. I need to do more than move a few boxes around and help topics within boxes. The whole concept of boxes is bad in the first place. Give me the ability to fix it.
Giving moderators the ability to edit the entire page isn't something that's likely to be possible, or something that we'd have the appetite for doing given that there's certain information we have to ensure is on there and other information about the network that we want to be included for every community.
I wouldn't have a problem with links to certain pages being mandatory, or someone from Codidact having to approve edits to the top level page. I don't expect that's something that would change a lot.
I still want to be able to set the whole presentation, which includes all the Codidact mandatory stuff. However, while I understand that stuff may need to be there for legal reasons, it gives all the wrong impressions when it's featured as if it were the most important thing.
I can't say until experimenting exactly how I'd want to structure the main help page, but without the flexibility I'll never have a chance to try. It's one of those things that I want to write it, look at it from different points of view, think about it a while, tweak, repeat, etc, until something I'm happy with finally emerges. I have some ideas, but I won't really know it until I see it.
You're right, what I'm talking about is not specific to Electrical Engineering. I'd be willing to work with you guys if you make the EE help an editable page, like other articles. If we end up with something we both like, then other sites can use that as their starting point if they like. It will be rather easy to strip out and replace the EE-specific stuff, which will mostly be links in the top level page. I wasn't planning on re-writing the EE help there is so far, nor the existing Codidact help, just creating a much better structure around it all in the top page.
0 comment threads