readthedocs / readthedocs/website
Idea for developer product page
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 21
- Forks
- 10
- Avg merge
- 3d 18h
- Merged PRs (30d)
- 8
Description
Okay, so here's a great/awful idea I head for the developer product page. The concept is that we're speaking to developers, so let's speak to developers using visuals they are familiar with. This has added benefit in that we can lightly explain the process they would normally be using when interacting with their project on Read the Docs, however the goal would probably be more abstract in it's execution.
That is, don't just show a pile of commands that developers would normally execute, but integrate our messaging in the output page through mock commands and maybe some sillier interactions. Here's a quick example, but I think we could really take this a bit farther than I have:

A few additions we're sneaking in:
- It shows reST!
- Links to actual example docs (maybe even a fake documentation domain?)
- Links to actual RTD features, ie a pull request build?
- Links in reST format are actually HTML formatted, clickable links
- Perhaps we sneak in features like embed API hovers even
What's neat about this design is it is very easy for us to produce, while still providing a visual representation of our process, without producing graphical elements.
I wrote this from the perspective of a user using RTD for a project as well, that is maybe negotiable, but does feel maybe less gimmicky than just explaining RTD from our perspective, but in a console.
There would be some hurdles where we might need some creative solutions:
- When we want to highlight something that happens in the RTD UI, we might not be able to show that to the reader. However, the point with this page could be that the developer is not interacting with RTD in this process, we automate all the work.
- At some point we might be out of creative options. Outputting a pygmentized reST source is clever, but we probably can't reuse that too many times. This will also require some creativity -- for instance the
readthedocs.yamlfile is an example of a useful file that is also documenting and explaining the process.
Thoughts? @nienn is this maybe too far out there? It's definitely more on the marketing side of tone, instead of being just purely informational. It doesn't take itself seriously though, which has be a small part of our brand historically. It's perhaps obtuse to some readers, but that is definitely where separate product pages come in.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
The issue does not name a file, test, or entry point; start by reviewing the linked mockup and the developer product page scope described here. Clarify which interactions and Read the Docs features are in scope, then define visual and content acceptance criteria before implementation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- html
- Domain
- design, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100