Documentation: Broad Sphinx-generated site design for review

[Hamish Willee]

Hi All

The proposed site layout design is available for your comment:

• Prototype on drop box 
  
• Design Proposal (explanation and context)
  

The main elements covered are the header, footer and sidebar. The content of the home page has been discussed, but not yet planned or implemented (there are some open questions with Alon and Jukka, and in any case I want to think more about an appropriate "10 second quickstart" on the front page).

I have made some changes to the read-the-docs theme including addition of the header with dynamic resizing of text, footer, emscripten logo, and support for more than 2 levels of depth in the sidebar toc. 

The prototype will have more work to make it more "professional looking" - but at this time I'm keen to move on with the documentation. Some examples include

• Navbar:  A more fluid layout. Making the links look like buttons. Perhaps a more fluid layout rather table layout. Layout on a bar that extends to the left side of the sidebar. Highlighting of navbar button for selected site section (e.g. docs)
  
• Home - hiding of the navbar on HOME (maybe)
  
• Footer - better layout of the footer links. More attractive copyright text.
  

Where I'd really appreciate feedback is:

• Content of the header and footer - are these the right options? Are there better ones or additional ones? Are the links right but the text wrong (note that the text changes on mobile - you can test this by shrinking the browser window horizontally)
  
• Colour schemes you might prefer
  
• Are you happy that this is the right approach for the site and layout? (checkout the Design Proposal for reasoning)
  

Hope you like it. Time to start populating the content!

Regards

H

[Alon Zakai]

Looks like a great start!

I see mention of mobile-friendly layout there. How much of that is done automatically by Sphinx? Hopefully we don't need to do much ourselves for that.

Header looks good. I wonder if we can use a github "fork this repo" side banner? e.g. as used on http://kripken.github.io/lua.vm.js/lua.vm.js.html Or in some other way make it clear its linking to github.

Footer:

 * Copyright should be Emscripten Contributors (perhaps with a mention "see AUTHORS.txt"). Speaking of which we should get you into there.

 * I personally think we don't need "Core Team".

 * "News" feels like it should be somewhere else than the footer? Perhaps a section on the front page?

- Alon

--
You received this message because you are subscribed to the Google Groups "emscripten-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-disc...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Chad Austin]

Wow, huge improvement!  I think it looks great overall.

At this point in the project's lifecycle, you might want a prominent link to a "Getting Started" tutorial.

On Sun, Jul 6, 2014 at 7:29 PM, Hamish Willee <hamish...@gmail.com> wrote:

--
You received this message because you are subscribed to the Google Groups "emscripten-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to emscripten-disc...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Chad Austin

Technical Director, IMVU

http://engineering.imvu.com

http://chadaustin.me

[Hamish Willee]

Thanks Alon, Chad - glad you like where we're going.

FYI, I have created a page for tracking changes I make in new builds: https://dl.dropboxusercontent.com/u/3067678/emscripten-site/deleteme_sitechanges.html#changelists 

@Chad

>At this point in the project's lifecycle, you might want a prominent link to a "Getting Started" tutorial.

Yes indeed! My plan was to have a prominent link as part of the main quickstart on the home page. I was also considering having it as the first item in the sidebar.

I didn't want to have it on the main nav-bar because it's not something you need as an experienced user (even though I do get your point that we're early in the lifecycle). 

What do you think - quickstart on home page enough? We should review this when the home page is done.

@Alon, 

> I see mention of mobile-friendly layout there. How much of that is done automatically by Sphinx? Hopefully we don't need to do much ourselves for that.

Almost everything is already done for us :-) Layout of the content is controlled by theme - and I've selected this theme that looks good on desktop, but which is already considered "mobile friendly". You can test this by shrinking the width of the browser window. 

From an authoring point of view there is no special work to support mobile as the content gets rendered as defined by the theme.

There is some minor work to be done still in my opinion - some are simple like adding a "Go to TOP" button at the bottom of the page along with the Prev/Next buttons. I'm also not completely happy with the way that the sidebar works on a mobile browser.

> Header looks good. I wonder if we can use a github "fork this repo" side banner? e.g. as used on http://kripken.github.io/lua.vm.js/lua.vm.js.html Or in some other way make it clear its linking to github.

I thought the "Github Project" link at the top right of the main navigation bar would be sufficient! Note that these buttons will be more prominent in later iteration of CSS.

Or was it that you wanted a "fork me" link somewhere? 

We could put something like this on the home page as well. I've added a note to the home page text that additional highlighting of the Github project is another signpost we might want. 

>Footer:

> * Copyright should be Emscripten Contributors (perhaps with a mention "see AUTHORS.txt"). Speaking of which we should get you into there.

Done - text changed and is now a link to the AUTHORS.txt

> * I personally think we don't need "Core Team".

I agree (removed). This was suggested in the earlier thread, but IMO not needed if we're linking prominently to AUTHORs.text int he "Emscripten Contributors" list.

This might however make a good wiki topic if someone wants that.

 * "News" feels like it should be somewhere else than the footer? Perhaps a section on the front page?

News will definitely appear in some sort of signpost on the home page. 

I have removed it from the footer as I agree it is unlikely someone wanting to see news would expect to see it here. Also because it doesn't make sense based on my assumption below:

Assumption: You want to do news in the same way as currently - just as a set of links on the front page, with old news disappearing when you update this signpost (the alternative is to have news more like a "blog" with separate pages for each news items - ie news is actually maintained on the site and searchable)

Regards

Hamish

--
You received this message because you are subscribed to a topic in the Google Groups "emscripten-discuss" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/emscripten-discuss/256zAMUrNJk/unsubscribe.
To unsubscribe from this group and all its topics, send an email to emscripten-disc...@googlegroups.com.

[Alon Zakai]

On Mon, Jul 7, 2014 at 7:17 PM, Hamish Willee <hamish...@gmail.com> wrote:

> Header looks good. I wonder if we can use a github "fork this repo" side banner? e.g. as used on http://kripken.github.io/lua.vm.js/lua.vm.js.html Or in some other way make it clear its linking to github.

I thought the "Github Project" link at the top right of the main navigation bar would be sufficient! Note that these buttons will be more prominent in later iteration of CSS.

Or was it that you wanted a "fork me" link somewhere? 

We could put something like this on the home page as well. I've added a note to the home page text that additional highlighting of the Github project is another signpost we might want. 

Well, my motivation is that the "fork me" banner or link+github logo is visually very obviously something that leads to github. Developers are very very familiar with the appearance of such links, so it's the fastest way for them to quickly (1) see that the project has its source available to them on the most familiar site, and (2) where on the page that link is, without scanning it to look. I agree "github project" has the same information, but the logo or the styled banner is just more effective, that's all.

 

>Footer:

> * Copyright should be Emscripten Contributors (perhaps with a mention "see AUTHORS.txt"). Speaking of which we should get you into there.

Done - text changed and is now a link to the AUTHORS.txt

> * I personally think we don't need "Core Team".

I agree (removed). This was suggested in the earlier thread, but IMO not needed if we're linking prominently to AUTHORs.text int he "Emscripten Contributors" list.

This might however make a good wiki topic if someone wants that.

 * "News" feels like it should be somewhere else than the footer? Perhaps a section on the front page?

News will definitely appear in some sort of signpost on the home page. 

I have removed it from the footer as I agree it is unlikely someone wanting to see news would expect to see it here. Also because it doesn't make sense based on my assumption below:

Assumption: You want to do news in the same way as currently - just as a set of links on the front page, with old news disappearing when you update this signpost (the alternative is to have news more like a "blog" with separate pages for each news items - ie news is actually maintained on the site and searchable)

Yes, exactly.

- Alon

[Hamish Willee]

> Header looks good. I wonder if we can use a github "fork this repo" side banner? e.g. as used on http://kripken.github.io/lua.vm.js/lua.vm.js.html Or in some other way make it clear its linking to github.

I thought the "Github Project" link at the top right of the main navigation bar would be sufficient! Note that these buttons will be more prominent in later iteration of CSS.

Or was it that you wanted a "fork me" link somewhere? 

We could put something like this on the home page as well. I've added a note to the home page text that additional highlighting of the Github project is another signpost we might want. 

Well, my motivation is that the "fork me" banner or link+github logo is visually very obviously something that leads to github. Developers are very very familiar with the appearance of such links, so it's the fastest way for them to quickly (1) see that the project has its source available to them on the most familiar site, and (2) where on the page that link is, without scanning it to look. I agree "github project" has the same information, but the logo or the styled banner is just more effective, that's all.

Thanks for clarification - agreed. I've added the following to the plan on Trello: Header: Investigate more prominent "Link to Github". Suggestion something like "Fork this repo" on http://kripken.github.io/lua.vm.js/lua.vm.js.html

How we address this will depend on the resolution of other other UI suggestions (like making the page center-aligned). I am recording these requirements but will concentrate on getting some of the content done before they are addressed.