Idea for developer product page

[agjohnson]

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.yaml file 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.

[nienn]

I love the terminal analogy but I wouldn't use it as a full page and not by it self.

let's speak to developers using visuals they are familiar with.

I agree with this 100%! Using the terminal, with all the extra artefacts you mention, is great.
My thoughts on using it as a full page, however, are these:

We need landing pages to explain the product in a different, less dense and less technical way than the one we already use on our docs. A full page terminal speaks to the developer but it does not make use of any of the benefits we can have in a landing page, as opposed to our docs.

I believe we want to make use of these benefits because, although developers can read and understand reST, it takes longer to process, and they also have the same needs as other users regarding the mental process of taking in a new product or a new concept.

We all have stages in our learning that benefit from being more visual than textual. I believe the first contact with a new product falls here. Graphics allow us to skim the content back and forth while organizing a generic idea of what we are dealing with and compartmentalizing initial concepts.

Also, we are all, each individual, very different people with different fleeting views and focus points. Graphics allow us to jump ahead to content that makes more sense to us at the moment and back again to content we skipped when it makes sense for us to take it in.

We won't be able to use artifices that benefit this learning process later on, when the content gets too dense and with a strict reading direction, but we can use them here.

A full page terminal has some funny quirks in a way it speaks to the developer, but I think we could achieve the same in a more manageable way.

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

I like this too. Using the terminal to showcase doc features and the development process is great!

I think we can divide the terminal into very small chunks, using all these artifacts you mention, but intercalate them with text, and possibly other graphics. The terminal chunks would be read as graphics too, and in order to function as graphics, wouldn't use more than just a few lines each. IMO and in the specific context of illustrative graphics on the landing pages, if someone has to stop to focus on and read a block, than that block is too long.

[agjohnson]

I think we can divide the terminal into very small chunks, using all these artifacts you mention, but intercalate them with text, and possibly other graphics.

I realized right after I put up this issue that a sidebar could be useful on both counts here. I'd be fine testing this concept and disregarding mobile for now.

I also wouldn't mind some additional content to break it up, but would have to see it in application first. I would guess that if this was broken up into multiple blocks of content, the effect will be lost, and it will just look like a series of code samples.

If the issue is being able to visually scan the output, we could do something to accomplish this, and provide linking to sections, etc. I think the sidebar might have a stronger application here though.

However, this could just be a supporting page, separate from the developer product page. Or this could be the initial pass at a developer product page and we come back to give a feature dense version. However, our docs do cover a lot here, and I see this particular page serving the purpose of engaging the user rather than explaining our product to the user. Our docs probably explain the process to users, the job of this page might be to point the user to the resources they are looking for more details on.

Is your opinion that this could be a developer product page, or does it make sense to treat this as separate and try both?

[agjohnson]

Also, regarding how users might interact with the page, we can also get creative with how we treat output in the terminal, making the terminal output look just like text, but have all of the functionality that we need in an HTML page -- headings, table of contents, etc. The goal isn't to make this look like the terminal that a user would actually use, but instead is just the output that includes the messaging that we want. This gives us a lot of room to work in solutions for scanning the content, while staying true to the underlying concept here.

[nienn]

Is your opinion that this could be a developer product page, or does it make sense to treat this as separate and try both?

Also, regarding how users might interact with the page, we can also get creative with how we treat output in the terminal, making the terminal output look just like text, but have all of the functionality that we need in an HTML page -- headings, table of contents, etc. The goal isn't to make this look like the terminal that a user would actually use, but instead is just the output that includes the messaging that we want. This gives us a lot of room to work in solutions for scanning the content, while staying true to the underlying concept here.

I'm not sure. If we find a way to do it exactly right, it can work, but I'm afraid it's easy to make the content too dense, too much like the technical structure of the docs and not gain much of the benefits of having a landing page.

But maybe we can start progressing in this direction. It will be easier to get input from the backend team for content in this format and we can even launch and start testing. Later, if it seems to be too dense for a landing page we can separate it and create a new page with much the same contents already defined here.