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.
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.
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.
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!
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.
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.
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.
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?
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!
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?
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.
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!
We use Discourse as an issue tracker. Better said – I try to force my team to use Discourse as an issue tracker And a wiki, and a forum, and a documentation… I suspect CDCK team to have another “secret” Discourse site where they track their stuff internally, using some interesting plug-ins, no-one has…
No matter how good the issue tracker is here, the community cannot be compared to anything else I know. In the end it’s the people who develop the software, not the technology behind it. And they rock!
And I like the documentation plugin a lot.
Now with all my praise, would it be possible to approve my PR?
We do have another site we use internally and that is indeed how we track much of our work. But we don’t do so with any secret plugins.
Mostly, we use conventions, like a category for “todos” and a standard set of a few tags for a kind of now/next/later prioritization, along with the assign plugin to clarify ownership.
That enables the kanban theme component to work too, but not everyone uses that view.
It’s pretty fluid, not a highly opinionated issue tracker, but it works well for us.
The new plugin in action
Transitioning from the Discourse Docs plugin
Let us know what you think
