search

readthedocs / website

The Read the Docs community website
15 stars 5 forks source link

Post: Empower your documentation with addons #278

Closed humitos closed 2 months ago

humitos commented 3 months ago

Initial work from our Book Club meeting.

📚 Documentation preview 📚: https://readthedocs-about--278.org.readthedocs.build/blog/2024/04/enable-beta-addons/

humitos commented 2 months ago

I pushed the latest changes. This blog post is ready to review.

humitos commented 2 months ago

I'd love to see a post that just announces Addons general availability, and explains a bit about how they work, without diving into each Addon specifically.

We published a blog post explaining the news around addons and how to enable them via build.commands (we didn't have the new dashboard by that time) some time ago at https://blog.readthedocs.com/addons-flyout-menu-beta/

I think people can get deeper into the specific ones via our docs or GH Readme, but this post should probably just be announcing general availability?

IMHO, pointing users to GH readme isn't a good approach and I'd try to avoid it. I created that page originally because it was the only thing we had at that time. Currently, we don't have any documentation page to link people to that describes the addons or how to enable them.

The idea behind explaining each of them in this post was to cover the lack of documentation on the addons we currently have while communicating our users how to enable them via the new dashboard. I'm seeing this blog post as a "temporal solution" while we write the proper documentation for addons.

I agree it's a bit overwhelming as you said, in particular because it's too long --but I still think it does a good job by captivating user's attention quickly with the screenshots let them know what are the features they can enable on their projects. It probably makes sense to move the section about "How to enable addons" to be before the full list of addons so the call to action is in the beginning of the post and people can start testing it without having to go to the end of the post. What do you think?

If we feel that this post is close, I'm fine shipping it, but if it helps to get things shipped to scale it back, I'm also in favor of that idea.

If we want to shrink it, what sections would you leave in the blog post?

humitos commented 2 months ago

I pushed some small suggestions changes and move the "How to enable addons" section above. I think it makes more sense now since people can enable them without reading the full post if they don't want 👍🏼 . I'd merge this as-is for now and continue working on writing down more detailed content in our documentation as part of