search

readthedocs / website

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

Page: docs-as-code #194

Closed humitos closed 9 months ago

humitos commented 1 year ago

Initial work to talk about "Docs-as-code concept" and how it's integrated with Read the Docs getting the main features by default thanks to the readthedocs-client.js.

The idea is to expose all these main features as https://github.com/readthedocs/readthedocs-client does by talking about docs-as-code and "all the doctools".

At the bottom there should be a copy&paste examples with one pretty known doctool different than Sphinx and MkDocs (maybe Docusaurus).

📚 Rendered version of this page: https://read-the-docs-website--194.com.readthedocs.build/docs-as-code/

:books: Documentation preview :books:: https://read-the-docs-website--194.com.readthedocs.build/

ericholscher commented 11 months ago

I'd be curious to get this merged just to get it ranking on Google, and we can improve it over time. I'll do a quick once over before we ship it. I'd love a better pattern for showing the 4 "items" on the right are actually clickable headings.

ericholscher commented 11 months ago

Actually looking at this more, it seems like it's a "addons" or "documentation features" landing page more than docs as code? It doesn't really talk about docs as code at all. That's not a bad thing -- perhaps we can reframe it to focus on readers?

humitos commented 10 months ago

My goal here was not to explain what "Docs-as-code means". I think we can briefly mention it in one sentence or similar. My idea with this page is to attract people looking for "Docs as code hosting" and tell them that we support the workflow they want and we add a lot of good features on top of that automatically.

On this page, I'm assuming that people looking for "docs as code" already know what that means.

humitos commented 10 months ago

@ericholscher I updated this page to show the addon features in a nice way. There are some work to do with the copy still, but I think the general idea is OK. I also want to use a Docusaurus example for the images, but I think it will be easier next week after deploying all the addons.

humitos commented 10 months ago

I also want to use a Docusaurus example for the images, but I think it will be easier next week after deploying all the addons.

I updated the PR to use Docusaurus images for the examples 👍🏼 . I think it's looking a lot better now.