Consider including a complete TOC on the landing page

[karafecho]

This issue is to suggest that the landing page of the documentation includes a complete TOC (table of contents) on the left side. As is, the TOC is very sparse and doesn't align with even the bullets at the end of the landing page. My concerns is that users (1) may not realize how rich the content is and (2) may not know exactly how to navigate the doc.

[vemonet]

Hi @karafecho

Currently browsing the Translator tech docs happens in "2 dimensions":

• Main sections at the tops: About, Architecture, Developer Guide, Admin guide (and Teams to be removed)
• When a main section is clicked there is TOC of the current section on the left

If I understand well you propose to stop using the main sections at the tops to put all the content on the left?

I agree the current layout has too many top sections

But personally I like this 2D approach, that allows reader to focus on sections. Being able to see all possible pages in one glance would be overwhelming I think. For example the architecture section TOC is already quite dense: https://ncatstranslator.github.io/TranslatorTechnicalDocumentation/architecture/

If we mix architecture + dev docs it's going to be quite large

But maybe we can reduce the amount of top sections? The About section is a bit useless right now, it could be merged with architecture. Same we could have "Administrator Guide" within the "Developer Guide" section. Which would leave us with 2 main sections to the docs:

• Architecture: pages explaining the technical architecture of the system, its standards, etc (no code, maybe just a few TRAPI queries)
• Developer Guide: pages guiding developers to use tools and standards from the Translator project (code examples)

This would be much easier for user to search for something (they need to check only 2 sections if they are lost), and this would avoid to have one huge overwhelming list of things (and people can always use the search box if needed)

What do you think?

[RichardBruskiewich]

Hi @karafecho and @vemonet,
I think both of your points of view have merit.
I agree with Vincent that aggregating too much in the sidebar will overload the user. That said, reducing the number of top level sections is a sound idea, although please give me some time to ponder exactly how to cut to pie, and get back to you.
Cordially
Richard

[karafecho]

You may want to solicit another opinion. Just a thought.

[RichardBruskiewich]

Hello again @karafecho and @vemonet, your initial feedback above inspired a rather ambitious refactoring of the documentation indexing and organization. I hope that it improved the product.. committed as cc92597

[vemonet]

I was also looking into it @RichardBruskiewich :D

I tried also to remove the tab and put everything in one main tab, and that is still quite readable

I deployed it on my fork to be able to compare: https://vemonet.github.io/TranslatorTechnicalDocumentation/

[karafecho]

@RichardBruskiewich : Where are you updates deployed? I am receiving a 404 error when trying to access https://ncatstranslator.github.io/translator-developer-documentation/.

[RichardBruskiewich]

@RichardBruskiewich : Where are you updates deployed? I am receiving a 404 error when trying to access https://ncatstranslator.github.io/translator-developer-documentation/.

Good morning @karafecho,

I guess you had bookmarked the site awhile ago, right? Are you clicking a link on the Github web site to access the site. You'll note on the main page README and the sidebar project description with URL, that the URL has changed.

LOL, you probably don't realized it but you do know the reason for this (once I explain it).

As we agreed and as I announced on Slack some days ago, the project Github project itself was renamed from translator-developer-documentation to TranslatorTechnicalDocumentation hence the corresponding Github pages web URL changed. As shown on the main Github site page, the updated URL is now https://ncatstranslator.github.io/TranslatorTechnicalDocumentation/.

[RichardBruskiewich]

@vemonet, @nlharris observed "...the very dark purple used for hyperlinks is very hard to distinguish from the black (dark grey?) regular text...".

I've created a docs/stylesheets/extra.css file to successfully customize the mkdocs 'material' web colors to meet the Translator media standard; however, I've been having difficulty figuring out which CSS property (from the mkdocs Material SCSS) to tweak for the URL ("HTML a tag") links.

I would like it set to the official dark blue Translator color code (several formalisms given... probably just need the hex rgb?)

PMS 661
CMYK: 100, 86, 14, 4
RGB: 0, 53, 148
HEX: #003494

Can you figure this out?

[karafecho]

@RichardBruskiewich : Yeah, I had not updated my bookmark. Sorry! I was in a rush trying to get to a parent-teacher conference.

@vemonet : I really like this version, as (1) the sidebar/TOC provides a high-level overview of not only the contents of the doc, but also the Translator architecture / operations/ etc , and (2) the sidebar/TOC makes it easy to navigate to sections of interest.

Richard/Nomi's suggestions re the color scheme are good.

Maybe run both of the refactored versions past a few more folks and see what they think? The UI team might have some good suggestions. Just a thought ...

[RichardBruskiewich]

@vemonet, I do concur with @karafecho that your latest version on your fork:

https://vemonet.github.io/TranslatorTechnicalDocumentation/ is the best menu design so far. Although we could ask the UI team for feedback, I would be content to see you push your latest design as a PR to the main project, for redeployment, then we ask the UI team feedback, OK?

If you can fix the colours of your forked project as noted above (#51 (comment))

[vemonet]

Hi @RichardBruskiewich and @karafecho , I must say in the end I find it also more readable :) I just made the change for the TOC and sent a PR

For the links color, it seems like the changes you have made @RichardBruskiewich are working well, on my side I see the links using the Translator purple (#003494), is it right? Or do you want to change it to something else?

Just when we hover the color is back to blue, but we should be able to fix it by changing variables like --md-accent-fg-color

[nlharris]

The "Translator purple" is too dark; it doesn't look like a fresh hyperlink (at best, it looks like an already-followed hyperlink, even when it's not). It is barely distinguishable from the black non-hyperlinked text. If you really want to keep the dark purple, rather than the normal hyperlink blue, maybe you could underline the hyperlinked text, which would make it a lot easier to see.