New documentation plugin in development

Announcements
,
1

We have recently made our new documentation plugin available for testing and feedback. This plugin is designed to enhance the navigation and accessibility of documentation hosted on Discourse, providing a more accessible and friendly experience for all users. Note that this plugin is still in development.

The development of this plugin stems from our ongoing effort to improve documentation, which has already been enhanced by a new sidebar. The sidebar work laid the foundation for a much improved documentation experience, and the new plugin incrementally builds upon that work.

:boom: The new plugin in action

The plugin is currently active and powering the documentation on our official Discourse documentation. We invite you to explore its features and share your experiences with us. Your feedback is invaluable in helping us refine and enhance the plugin.

The core features included in the new plugin are:

  • Settings to define which categories are used for documentation
  • A new documentation sidebar populated by index topics within each category
  • Two new reports to help maintain the integrity and accuracy of index topics

With more in development as we continually improve the available features.

The new plugin is available to download and install today: Discourse Doc Categories

:electric_plug: Transitioning from the Discourse Docs plugin

As we innovate and move forward, we will be sunsetting our older Discourse Docs plugin. You can rest assured, however, that we will continue to support it until the new plugin is fully ready for a widespread release. We have also ensured that the new plugin will redirect URLs from the old plugin, so switching over won’t result in any broken links.

Please note that the new plugin is still in its experimental stages. While we aim to provide a seamless experience, there may be some areas that require further improvement. Your constructive feedback will be crucial to its success.

:speaking_head: Let us know what you think

We would appreciate your thoughts, experiences, and feedback. Feel free to share your experiences and any insights you gather while using the new documentation plugin, either by navigating through the documentation on Meta, or installing the plugin on your own site.

Our goal is to shape a better documentation experience for the entire Discourse community, so all feedback is welcome!

Full plugin details available here:

11 Likes
2

Someone needs to update the readme. And maybe update the lint rules to keep this from happening, though there is a chicken/egg issue.

It looks like it could also be great for using Discourse as an LMS. For that it would be good to be able to switch which category was a documentation category, though there’s a good chance that just using permissions to give users access to certain categories is enough for it to Just Work.

7 Likes
3

Good catch of the URL - I just submitted a PR to add that.

Sounds like an interesting use-case for this, and I can see how that would work quite nicely!

6 Likes
4

This is a fantastic improvement over the original Docs/knowledge base plugin. So far seems very user friendly.

Testing on Meta definitely a huge plus as the docs categories here can be hard to find things previously.

5 Likes
5

Dare I ask for an ETA? I.e when this plugin will be considered less experimental and more in a beta, or perhaps even early release candidate stage? I know how hard it is to predict the future, so I’ll be happy with any rough estimate, however inaccurate it may be. :wink:

I’m currently exploring Discourse as a tool at work, exactly because it seems to be able to offer a good mix of community discussions and a shared and space for documentation. Where it is as easy to write documentation as it is posting a comment on a topic.

So, the wiki topic feature by itself is neat of course, that’s a great start. This plugin though, it adds cohesion to the content of the topics, which I believe is essential for the user experience of documentation.

The Documentation category on meta.discourse.org now feel like a proper structured documentation site, rather than just some random forum topics that happen to share a category and happen to describe how Discourse works.

So, keep up the good work. Thanks!

1 Like
7

I super like it! Documetation and Discourses fits very well together.

Do you have plans to enable indexing of tags in addition to categories?

8

I think the stage we are in right now is “beauty (or lack thereof) is in the eye of the beholder”

It’s experimental in the sense that there are known UX issues, particular for those responsible for maintaining the documentation and especially the indices, but it’s completely safe to use in production.

All that is to say, we’d very much welcome your feedback if you try it out and kick the tires yourself.

We don’t have any ETA at this point for improving the known UX issues with index maintenance, but feedback from people using it may help drive the direction there.

Nope, this isn’t something that has come up anywhere yet. Can you share a bit more about what you’re thinking or why this would be helpful for you?

2 Likes
9

About this: If you are on a doc category, and close a non-fullscreen chat window, the doc navigation is also “closed” and the regular navbar is showing again. While repro on meta, I also noticed clicking the chat bubble (top right header) it also closes the doc nav. Hope this helps!

3 Likes
11

Thanks for reporting this - I’m able to reproduce, so have logged this, and we’ll include it in the upcoming development work here.

3 Likes
13

That reminds me of one thing with Discourse as a project, that isn’t really ideal to me as a user. The fact that the project does not use a proper public issue tracker for bugs and planning.

E.g, when I read Hugh’s response, my internal project manager immediately raised the question: where, where was this logged?. I know, my internal PM is a nosy little creature, isn’t he? :slight_smile:

I suppose using meta.discourse.org as an issue tracker gives the project an opportunity for “dogfooding” Discourse. And all other issue trackers have their own faults, so it’s a pain having to choose one. But to me Discourse - while being excellent as a forum for questions and discussions - is very lacking as an issue tracker. For that purpose it lacks effective categorization, info about affected and target versions, issue numbers, prioritization, effective means to filter issues by status, age, priority, product or compoents, and a good way to present a roadmap for a feature or the product as a whole, among other things.

Well, I digress. And I haven’t contributed a single line of code, bug report, or feature request yet, so who am I to complain. :wink:

So, again, thank you all for the awesomeness of Discourse. And pardon the semi-rant.

And on topic, great to hear that Discourse Doc Categories, while not polished yet, is considered architecturally stable. I’ll check if I can get it installed on my hosted Discourse instance, and if so try to return with feedback. Thanks!

4 Likes