search

monome / docs

monome.org/docs
https://monome.org/docs
Creative Commons Attribution 4.0 International
127 stars 85 forks source link

Add a navigation to docs pages #164

Closed aidanreilly closed 4 years ago

aidanreilly commented 4 years ago

A left hand navigation would be beneficial for users. it's expected for most docs sites IMO.

tehn commented 4 years ago

agreed. see TT manual. https://monome.org/docs/modular/teletype/manual/

basically we need a redesign proposal.

oliviercreurer commented 4 years ago

Gonna try to put a small proposal together today (mostly a collection of mocks as a starting point for discussion). Will post here when ready!

aidanreilly commented 4 years ago

cool :) In the meantime, still playing with jekyll. I added the yaml front matter to the crow docs to see what they look like in the left hand nav: https://aidanreilly.github.io/docs/crow

updated in parent topic: image and in the child topic: image

aidanreilly commented 4 years ago

made a small change to the default layout for in page TOC generation. the default was to put a TOC at the bottom of the page for some reason. Moved TOC to the top. example: https://aidanreilly.github.io/docs/crow

oliviercreurer commented 4 years ago

@tehn @aidanreilly @dndrks -- My proposal so far is to have a side navigation that, coupled with a significant reorganization of existing docs, would ensure that a user is ever only one level removed from the main index (at least in the wide majority of cases). Hopefully, with a structure like this, it becomes easier for users to keep a mental model as they read/learn, and it's easier also for potential contributors as they assess where to log their additions.

So, for instance, the main index's existing contents would be simplified and moved over to the navigation (which leaves plenty of space on the page itself for...something):

proposal_1

Clicking on an index category would bring you to a page where all of its documentation is aggregated and accessible from the side nav. Here are examples for grid, norns and crow:

proposal_2

Of course, this layout needs to be mobile-friendly as well. I'm thinking that, on mobile, once you navigate to a category, its nav sits at the top, sticky and collapsible as you scroll through the doc.

Open questions:

You can follow design work here. I'm using Whimsical (!), a basic wireframing tool, so keep in mind that styles would be refined.

tehn commented 4 years ago

@oliviercreurer those are some beautiful renders.

i really like the single sidebar, where essentially the ToC gets combined with the broader navigation.

i'm not sure how jekyll itself would auto-generate the sidebar, but i don't think it would be a stretch to do some sort of include directive as long as the content maintenance was relatively low--- basically i'm concerned about content getting out of sync with a manually-updated ToC/etc.

generally it seems that feedback has been a preference for broken-up pages, not the huge/infinite single-scroller. but i also think that's a reaction to the lack of navigation. in terms of organization--- with ansible as an example--- there isn't a great reason that CYCLES needs to be on the same page as KRIA--- as it was before the more recent breakup edit.

right now @aidanreilly the jekyll template seems like it'd need some editing to get this sidebar functionality. i'm definitely not in preference of the ToC being in the same column as the main content block.

maybe it's time to try some jekyll tests for achieving something like what @oliviercreurer is suggesting?

aidanreilly commented 4 years ago

Should be easy enough to pull the page TOC out into a separate block top right of the page, away from the main content. I'll see if I can do that when i get a chance. It'll need to sit on top of the content for mobile viewing of course.

Regarding @oliviercreurer 's suggestions - do we have some web folks that would be able to help with implementing these Nav suggestions?

Also - any further development on the Nav would need us to decide on a base template I think. Are we happy to proceed with this jekyll template? Incidentally, this just-the-docs template was developed by the head of GitHub product design, Patrick Marsceill: https://github.com/pmarsceill

If we decide on a template, then we can begin reworking the actual markdown content to support the new TOC and Nav features in parallel with any work to the jekyll theme css. Note I think the content can stay as is for the most part, all we need to update is yaml header items for *.md files.

aidanreilly commented 4 years ago

Also, regarding monolithic pages versus discrete topics - i'm very much in favor of discrete task-oriented topics. There is balance required here of course.

aidanreilly commented 4 years ago

Page level TOC could potentially just go away if the Nav could be made to do as Olivier’s designs suggest. that would probably be the optimal solution right?

oliviercreurer commented 4 years ago

basically i'm concerned about content getting out of sync with a manually-updated ToC/etc.

Yeah, I definitely hear and feel that. Ideally, the nav/ToCs should provide contributors with a clear and sufficiently broad categorization structure (in any context) that can easily accommodate new content. In other words, any changes to a specific ToC should be rare, deliberate and agreed upon.

Perhaps the main index page could now be comprised of best practices for contributions.

aidanreilly commented 4 years ago

FYI if we manage page level TOC from the individual topic headers, page level TOC gets auto-generated at build time.

tehn commented 4 years ago

@oliviercreurer i'm not sure hw feasible it is to merge the ToC (ie, links to headings in a particular page) with links to other pages

basically i feel just-the-docs is a good starting place. certainly it requires a bit of extra tagging but that's not a big deal. i am happy to take on the content portion.

but i would be very happy to get some design/css assistance. particularly with the mobile css stuff.

i'm going to start a development branch of the docs and base it on just-the-docs.

tehn commented 4 years ago

@aidanreilly your proof of concept with just-the-docs looks good--- just to clarify, i'm going to move around a lot of pages which is why i didn't just fork yours as a starting point

aidanreilly commented 4 years ago

Yup all good. My fork was just a quick POC. Happy to help however.

Aidan

On 22 Oct 2019, at 22:08, brian crabtree notifications@github.com wrote:

 @aidanreilly your proof of concept with just-the-docs looks good--- just to clarify, i'm going to move around a lot of pages which is why i didn't just fork yours as a starting point

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

tehn commented 4 years ago

changed my mind-- forked yours :)

aidanreilly commented 4 years ago

Wasn’t expecting this to be forked as source tbh. I chopped a lot of extra files and folders to quickly test the theme, footers, extra HTML templates, stuff like that. I guess anything that’s needed can just be put back.

Aidan

On 22 Oct 2019, at 22:28, brian crabtree notifications@github.com wrote:

 changed my mind-- forked yours :)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

oliviercreurer commented 4 years ago

@tehn Cool! Sorry about the radio silence on my end -- my 9-5 got a lot busier recently. Still happy to chip in for mobile design help/feedback as needed; my css skills, on the other hand, are pretty basic and limited.

tehn commented 4 years ago

@oliviercreurer no problem. would be happy to get your opinions when i get a beta layout posted. realized it was going to take me a bit of time given i should restructure the whole content while i do this :)

aidanreilly commented 4 years ago

Yes I kind of had the same realization looking at the docs. it's going to be a big job.