UX and Visual Design for Codewind Docs Landing Page

[kimholmes]

ID and Design to work together to improve the experience of this page: https://www.eclipse.org/codewind/gettingstarted.html

[kimholmes]

First pass. This is not a final design but a mid fidelity wireframe to begin iterations.

[MelHopper]

https://github.com/eclipse/codewind/issues/2108 created to cover creation of copy for the new docs landing page.

[kimholmes]

@MELANIEH 's comments (Kim's response in italics):

1. will the docs LP be designed to not require any scrolling to see the whole page on a desktop browser window (like Kitura)? Or are you planning on a page that scrolls on a desktop browser (like VS Code)? Looks like the first option - I have no preference, just so I understand the variables of the design.

The page can certainly scroll. We don't have total control over that given that it depends on the user's browser window. The page should be responsive regardless.

2. we're missing the 'Getting Started' artifact and 'product overview' artifact. A few ideas.... There was an idea to have the product overview showing explicitly on the page, scrollable...because it's crucial to expose very early on in the user journey (feedback is that new uesrs are finding it hard to understand what Codewind is for and how it will help them). But if that doesn't fit with your design, the alternative is to put this signposting within the content at the top i.e in the 'Documentation' section. I can create some draft copy for you if you like, to show how these links could be incorporated in that 2nd option?

Yes, please supply the Product Overview text I intentionally deleted what we previously had as "Getting Started" and integrated it into this page

3. Is it possible to add a section, similar to the 'Guides' and 'Videos' and 'Blogs' section, that is titled 'Getting Started'? Then in there we can signpost to the Getting Started tutorial in the docs, and also perhaps e.g. a blog that summarises it, and a video...so the user is immediately exposed to a Getting Started option....?

Certainly. We should consider using the Guides, Videos and Blogs section for that "getting started" type content. It will then link to them to all of those artifacts.

5. I really like the layout, really clear to the user. Especially like the Download section. Copy for Download: needs a bit of thought -Terminologies were nailed down with Rob to 'using Codewind locally, remotely or hosted' when describing the 3 different ways of using Codewind. The use of hybrid needs to be changed because hybrid implies the use of on-premise cloud offerings. Thinking caps on :brain: perhaps: for VS code, Eclipse (and IntelliJ): Download for building and running your applications locally or remotely for Eclipse: Download for development hosted entirely on your cloud and just a little thing - typo: it's 'OpenAPI Tools' in the Quick Links section.

FYI, here is the current Terminology that has been OK'd: https://ibm.ent.box.com/note/539884590107

For the url, it'll need to be something like codewind.dev/docs or codewind.dev/learn. The current page https://www.eclipse.org/codewind/gettingstarted.html is a topic within the ToC/left hand nav that will still exist, albeit in potentially a different form, even when the docs LP has been created.**

[MelHopper]

The 'Codewind on Kubernetes' link is blocked by ToC left hand nav restructure that will expose Kubernetes/cloud-based configs of Codewind. https://github.com/eclipse/codewind/issues/1980

[kimholmes]

For this comment above:

3. Is it possible to add a section, similar to the 'Guides' and 'Videos' and 'Blogs' section, that is titled 'Getting Started'? Then in there we can signpost to the Getting Started tutorial in the docs, and also perhaps e.g. a blog that summarises it, and a video...so the user is immediately exposed to a Getting Started option....?

I've included those to links as "learn more" and "see it in action" in the top section.

[kimholmes]

Vertical layout with right sidebar. Does not include full overview content.

Horizontal layout. No right sidebar. Does include full overview content.

[MelHopper]

Look fab @kimholmes, really like them, and great to be able to compare having a product overview explicitly on the page or not.

Very much like the 'learn more' and 'see it in action' links.

Can we add the other 2 Getting Started tutorial link bullets (Jane ones) to the Champ (Devops and defining standards) bullets you've got there?

• To jump in and get started using Codewind to develop and run your application on your desktop, see [Using Codewind Locally ](ADD  TOPIC)

• Or to use Codewind in your cloud environment, see [Using Codewind in your cloud environment](ADD TOPIC)

[MelHopper]

small change to 'Download' content: For VS Code etc.: Download to develop on your desktop and run either on your desktop or on your cloud

For Eclipse Che: Download to develop and run entirely on your cloud

[micgibso]

@kimholmes I like the layout of the first one, Quick links, social, blogs, and video links all nice and obvious. Out of the two, the first just feels more balanced.

If screen space/collateral etc is of the highest importance, we could have a See more getting started information link and then an expand/collapse section if you wanted the overview to have everything in it instead of being the shortened version - Amazon do this a lot on their web site.

But if I was coming to Codewind for the first time, I might like all content there in front of me. Appreciate it's tricky finding the balance, what's the UX/Design viewpoint on See more _nnn_ information links with expanding collapsing sections?

[kimholmes]

Thanks @MelHopper and @micgibso Michael. Yes, I really do like your idea of the expand collapse. I think it really depends on which layout we want to go with (an I prefer the first, lighter one, as well). I will include that feature in the next mock up.

In response to this comment from Mel: Can we add the other 2 Getting Started tutorial link bullets (Jane ones) to the Champ (Devops and defining standards) bullets you've got there?

To jump in and get started using Codewind to develop and run your application on your desktop, see [Using Codewind Locally ](ADD TOPIC)

Or to use Codewind in your cloud environment, see [Using Codewind in your cloud environment](ADD TOPIC)

I added those links to the appropriate Download buttons. Because that's what they should be associated with.

My only question is about the "run your application on your desktop" option. Shouldn't that be combined with remote or hybrid? That way we only have one link for the hybrid IDEs. Let's get together to discuss where all the links go.

[MelHopper]

@kimholmes small change - can we change the term 'docs' in the header or the website pages, that will link to the new docs landing page, to 'Learn'? (from UX perspective: we want users to know where to go to find out more about Codewind, whereas 'docs' doesn't have the same connotations, could imply a manual / too much detail vs. our 1 stop shop docs landing page for downloading, getting started, blogs etc.)

[MelHopper]

@kimholmes FYI I've (i) changed some of the copy https://github.com/eclipse/codewind/issues/2108 - it's in flux but we can discuss (ii) got a mural on the go for the multiple user workflows that we're going to discuss on our call today - maintains topics so that does not break external site links, but caters for all possible user workflows.

[bsbyrd1]

Great work, team! Any iteration plans for implementing and publishing this landing page?

[MelHopper]

Hi @bsbyrd1 Kim and I are currently working on refining the user workflows, iterating on the design of both this new docs landing page and the ToC + user workflow in the documentation...we're getting there. Once we have a final design, we can look at planning implementation of the docs landing page with @sghung and the github issues related to the ToC and Getting Started content enhancements.

[kimholmes]

Please provide feedback. We don't have to pick a specific page but can identify elements that we like and iterate on the design:

Here's a design with cards in the masthead that represent the different downloads (hybrid and remote):

A second layout option:

[j-c-berger]

Great work, Kim! I'm excited to see the final, published version!

I, personally, prefer the first layout option, because I am able to take everything in more all at once. For the second, I find myself reading it in chunks: 1, TOC on the left. 2, getting started in the middle. 3, quick guides and tweets on the right.

Of course, I'm not an expert opinion and shall agree with what the larger team decides :)

As far as elements that I like for design to iterate upon: I like that quick guides, blogs, and tweets are easily accessible and some of the first things users notice. That way, users can learn more about Codewind (to which extent is up to them) before they dive into development and read out docs in the TOC.

[kimholmes]

@sghung @MelHopper Here are specs for the landing page. Although I'm sending final specs over now, we can still make minor tweaks moving forward.

To view the HTML/CSS specs, load the index.html page in this zip file (this code does not need to be exact, but can be used as a guide): Docs_Landing.zip

Icons: DocsLanding_Icons.zip

Specs for cards (this code does not need to be exact, but can be used as a guide)

[MelHopper]

Hi @kimholmes @sghung , I'm just finishing up the website topic end points for the docs landing page / user workflow.

The step-by-step instructions for the Desktop and Remote artifact on your page are IDE-specific. We can solve this issue by changing the copy on that docs landing page artifact to:

step-by-step instructions for VS Code, Eclipse and IntelliJ

(In the future, ID team hope to implement tabs for the different IDEs, but this will not be in the next iteration or 2).

[kimholmes]

@MelHopper @sghung I can tweak the design to provide links to instructions for EACH IDE.

[MelHopper]

@jcockbain CSS/HTML specs for content landing page can be found in this Github issue - see above comments.

[MelHopper]

@kimholmes Hi Kim, we have a similar issue with the following copy if we are sunsetting the 'gettingstarted.md IDE-agnostic page':

If you are a developer, learn [how to set up and start using Codewind on your IDE](https://www.eclipse.org/codewind/gettingstarted.html)

We can either keep the gettingstarted.md file in (see the following screenshot for the interim content on that page until we have our content landing page and can redirect.

OR

change the copy to call out each IDE, in a similar way as the above comment on 'step-by-step instructions' copy.

OR

Another solution we come up with? (FYI we have a meeting on 18th May we can use to discuss this if no decisions in the meantime).

[kimholmes]

@MelHopper I would much prefer we tweak the design to accommodate links for each IDE. I have not done that yet and will be on vacation through May 19th. I understand if you have to move forward.

[MelHopper]

@MelHopper I would much prefer we tweak the design to accommodate links for each IDE. I have not done that yet and will be on vacation through May 19th. I understand if you have to move forward.

Great, thanks Kim. The gettingstarted.html topic will be sunset when the new landing page goes live.

[MelHopper]

Content Landing Page being implemented under https://github.com/eclipse/codewind/issues/2594

[kimholmes]

@MelHopper Just want to make sure I’ve answered these questions in full. You asked: Design: @holmesk How do we get users to want to click a’button’ to find more blogs? / go the blogs page? Link to ‘...more blogs’ exists, does link to Blogs page need to be more prominent e.g. with the title of the section also linking to the Blogs page? Asking Design. Same question for Guides and Video section.

1. The blogs and videos. There are 3 different ways the user is directed there on the landing page. We can link the titles to the blogs landing page as you’ve suggested. In James’ current version, there is a title that reads Media. So, we would need to remove that and give blogs and videos their own individual titles that link to the respective pages.
2. They can click on the title of the blog or video that is featured.
3. They can click the “more” link. Do you plan to include left nav items for guides, blogs and videos?

Your second question: _Design: @holmesk Where are we with the IDE-specific designs for https://github.com/eclipse/codewind/issues/2041#issuecomment-620639770: step-by-step-instructions in the Desktop/Remote section If you are a developer, learn how to set up and start using Codewind on your IDE in the ‘Get Started by Job Role -> Developer’ card_

For number 1. James has put a solution in his version of the page: Each individual IDE links to the installation instructions. I’m actually questioning whether or not the buttons should link to the instructions as well. Right now they are linking directly to the installation. For number 2 - by job role, James has done the same. Each are linking directly to individual IDE. Looks like we’re missing Che though.