Embedding Content From Your Documentation, blog post #83
Conversation
humitos
force-pushed
the
humitos/hoverxref
branch
from
df8707e to
6eb98a4
Compare
We have covered most of this feature in our guide at https://docs.readthedocs.io/en/stable/guides/embedding-content.html, so I don't think there is too much to add here. However, I think the blog is the right place to promote this feature and share a little of its story. I'd like to have an example of in-app UI tooltip, but the tool we built does not look nice and I don't think we want to promote that as is.
humitos
force-pushed
the
humitos/hoverxref
branch
from
6eb98a4 to
47ab241
Compare
|
The embed API is not stable on commercial, so we should probably get to some level of parity on commercial before we start talking about embedding as a feature. It's currently only a feature of community and so commercial users will be confused by this news. |
What do you mean by this? We deployed the Embed API some time ago in .com and I remember that it was working when we did some QA. I will double check this, anyways. |
|
I just built sphinx-hoverxref's documentation and it works: https://docs.ops.verbthenouns.com/projects/sphinx-hoverxref/en/proxied-endpoint/ (it builds a different branch than latest to use the proxied API instead of community URL as it was doing) |
|
That branch isn't active for me. |
|
I had a bunch of feedback here, so I went ahead and just took a swing at re-writing it. If we're going to be playful with the tone, we need to be really explicit and clear about what we're saying, because it can be confusing to people otherwise. I tried to keep a little of the playfulness, but keep it more obvious what we were talking about. |
|
Before we ship this, we should confirm the API is something we want to support. Currently we're returning We should also ship a screenshot of the dashboard embedding content (@agjohnson) |
|
Should we hold this off until readthedocs/readthedocs.org#8039 is merged? |
|
I'm fine publishing this. The current API has to be maintained anyways, so I'd say it's fine if people start using it. However, the most important goal of this post to me is the promotion of the Sphinx extension. Waiting for the new Embed API + JS client will be too much time, IMHO. |
There was a problem hiding this comment.
Thanks for trying to move this forward @humitos!
I did a rather uninspired review, sorry about that - I think I'm missing some context and I don't fully understand parts of the post, in particular about "our application". But I would love to finish this effort and bring the post to a publishable form next week.
| Our approach to embedding content is a very simple but powerful idea: | ||
| *return the content of a specific section from a particular document in a project*. | ||
|
|
||
| We have built an `Embed API`_ as the backend that powers this feature. |
There was a problem hiding this comment.
question: Shouldn't we decide on readthedocs/readthedocs.org#8107 first?
| Embedding Content From Your Documentation | ||
| ========================================= | ||
|
|
||
| We are excited to announce the release of content embedding. |
There was a problem hiding this comment.
question: Rephrase first line?
If I understand correctly, we have an embed API at the moment, and readthedocs/readthedocs.org#8039 discusses improvements to it. Therefore, if I understand correctly, this API has been present for some time (can trace exactly how much), and and we are making it known for users. Am I understanding correctly? If so, the sentence "we announce the release of content embedding" is a bit misleading to me because we are not releasing anything now (it's been there for some months already). Perhaps it is leaving experimental state? Or we just want to describe how it works?
Sorry this looks like a super nitpick, but I'd love to have a bit more context to frame the review correctly.
|
|
||
| Our first goal was adding extra context to a link within the same page. | ||
| This helps the reader understand a concept, | ||
| without switching context and jumping into another completely different page. |
There was a problem hiding this comment.
suggestion: make this sentence shorter
| without switching context and jumping into another completely different page. | |
| without having to jump into another completely different page. |
| .. _sphinx-hoverxref: https://sphinx-hoverxref.readthedocs.io/ | ||
| .. _reading the docs: https://sphinx-hoverxref.readthedocs.io/ | ||
|
|
||
| Inline help on our application website |
There was a problem hiding this comment.
thought: It took me a few seconds to understand what "our application website" meant.
I am not sure if there is a better term, or if we are using similar terminology in our docs that can be reused here.
|
|
||
| Adding too much copy in your application can be overwhelming to users, | ||
| meaning they don't read it. | ||
| We try to keep the application copy minimal, and link out to documentation when appropriate. |
There was a problem hiding this comment.
question: What does "the application copy" mean in this context?
| This pattern has worked fine over time, but it has the same problem of context switching to a completely different page. | ||
|
|
||
| Since we've started working on a new re-design of our entire application UI (more on this coming soon!), | ||
| we added the usage of the Embed API to add this extra documentation. |
There was a problem hiding this comment.
suggestion: Rephrase to avoid saying "add" twice in the same sentence?
| .. _read its full documentation: https://docs.readthedocs.io/en/stable/guides/embedding-content.html | ||
|
|
||
| We think it's a super powerful feature and we encourage you to use the extension we built on top of it, | ||
| or even better, build your own and share them with us! |
There was a problem hiding this comment.
nitpick: The tone looks a bit informal here.
I wonder if we should make it a bit more formal, in line with other blog posts.
|
I think we can close this PR since the work has been done in other places already. |
|
Wow, somehow I totally forgot about this blog post. We should have published it earlier. Thanks @humitos |
We have covered most of this feature in our guide at
https://docs.readthedocs.io/en/stable/guides/embedding-content.html, so I don't
think there is too much to add here. However, I think the blog is the right
place to promote this feature and share a little of its story.
I'd like to have an example of in-app UI tooltip, but the tool we built does not
look nice and I don't think we want to promote that as is.