Post: Empower your documentation with addons

[humitos]

Initial work from our Book Club meeting.

---

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

[humitos]

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

[ericholscher]

I looked at this post briefly, and got a bit overwhelmed. It seems like it's trying to do the same thing at the GH README, and has a bunch of TODOs in there. 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. 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?

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.

[ericholscher]

What is version feedback?

[humitos]

I'm not 100% sure. David wrote this description; but it could be either:

1. pull request, non-stable and latest notifications shown on top of the page
2. doc diff

We can make it more specific if we want like "version notifications" or "version differences"

[davidfischer]

I'm not sure what it means either and I wrote it.

[humitos]

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]

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

• Docs: create a page per doctool supported readthedocs.org#11187
• Docs: configuration guide content on new tools readthedocs.org#10418

[ericholscher]

This looks good to me, just a couple suggestions.

Also, if we're viewing this as user-facing docs, we should probably note docdiff required a hotkey to enable, I thought?

[ericholscher]

I feel like we're highlighting notifications in 3 sections... shouldn't we just combine them together and note that it supports each type as a bullet or similar? Seems like a lot of notifications, but it seems the new flyout, search, and docdiff are the big ones.

[humitos]

I don't have a strong opinion here. I think it's fine for now, and I like that we are showing them all in the screenshots with different doctools on each. We can find a different/better pattern for our own documentation if we want.