Docs home page: organization? #46
Comments
|
My idea: Main page can be as empty as possible, with a couple of ways to search for eventually interesting articles:
What you described makes IMO good candidates for Categories, so for example an article about kata trainer could be placed in both Solving and GUI. Generally I think that GUI is not even a good category, because... who'd need a reference to "whole" GUI in one place? Main direction docs are laid out IMO should be functions, activities and motivations of users reading them. Going this way, I would make Tutorials and FAQs a category. The question is, if they will stand out prominently enough to be easy to find by people searching for help. But this idea has a problem that I do not know if categories list can be composed in some nice way, or is it just a blob of links. If we could have some nice thumbnails etc. it would be great. But I do not know what's possible with our docs system, I didn't get too familiar with it, yet :( |
|
About the functionnality aspects, I agree with you. But, thing is, this way, you push the accessibility of the info one link further (even if these categories/tags/... things can be made something else that the blob of links) and most users won't like the idea to do that extra click. But you're right about keeping the number of icons as little as possible, to increase readability. |
|
I agree that it unfortunately brings things one click further, but maybe we could save/hint them this one additional click:
|
|
not really fond of the idea... Another one, keeping the "one click further" thing, but allowing to have a complete/detailed page: just add one item Table of contents and set up what I suggested in that page? EDIT: maybe even a second button under "get started", making the "table of contents" more obvious in the page? |
|
I'll rename
Not sure if I'm understanding your question, but the code for those 4 links are here: Lines 32 to 80 in cbbd483 As I said before, we're going to iterate on this and optimize as we go.
That's possible. We can change any styles.
I wasn't planning to add too much on the landing. The search will be super useful once we switch to DocSearch (#4) too.
Pretty much anything is possible because this is fully customizable (just a Vue app). I wasn't going to focus too much on organizing and styling yet until we have more docs, but we can start discussing it or consider start doing some of them. |
That's exactly what I thought categories to be, I was just wondering about presentation , if we could get such tiles or something. If we can, then great! |
I was just talking about their order. But since it's fully customizable, "whatever". Topic/categories: looks great, in that case, yeah. |
|
@Blind4Basics Can you elaborate on full table of contents? Is it a list of all pages and links to them? We should be able to generate one from the data. |
|
yes something like that, but with formatting, sections, and mostly a wanted order (just like in a book). It's surely doable automatically, yes, but I'mp not sure it's that easy to do. Maybe by adding an index to each main page/topic, then study the graph dependency, yes. But cycles will happen at some point... => ? |
|
Yeah, we should be able to do that dynamically by storing some information for ordering within the page data (or infer from
Another way is to have something statically defined like the sidebar: Lines 23 to 41 in 319c219 This is simple and pretty flexible about what to include and how to order, but can be annoying to keep updating. This is why I added a way to automatically generate a sidebar for pages related to the language with Anyways, we can do whatever that fits our needs and I think we should wait until we have more docs to understand what's best. |
|
The landing looks like this now:
Let's open a new issue for topics if you'd like to start collecting them. For documentation kinds, let's continue at #8. |
To get a better idea about how the thing will eventually work:
Currently:
Suggestions/questions:
So, I guess every "entry point" for documentation will land as an icon in the bottom part of the screen. This leads to some questions:
1) how are they organized?
reading through https://github.com/codewars/docs/blob/master/src/pages/Index.vue, it seems they are automatically displayed in the order the components are inserted into this file (
g-linkparts). Right?2) is it possible to visually separate them?
Like, to have line separations or something in the home page to split some icons from others?
3) when more things will be there, what general organization should we use?
On this, and if the previous point is possible, I'd see the following:
4) what other topics?
Here is the critical point, imo. 'Time to define some ways of splitting the docs so that we can have a better idea about where we are going.
I'd go for the followings (in random order and non exhaustive, ofc), the idea being that those categories could contain sub parts possibly used at several different places:
getting started (not sure if it's good to have it doubled with the link in the center of the page but...). See Add Getting Started doc #40
codewars general informations, that would roughly be filled with :
codewars UI (detailed/exhaustive version of what I suggested to add to the "getting started" part. Not entirely sure it deserves a specific topic, tho)
beta process
kata authoring and translating
(I put the info there otherwise it could be lost in zulip at some point:
authoring tutorial: give credit to the original source when needed)Codewars' users
tutorials (possibly linking other parts in the previous sections).
Maybe a FAQ section would be a good addition. That would only be another way for the users to go/access to informations spreaded in other places (idea comming from @Steffan153 's post on zulip )
Here are my 2 cents...
@kazk: is that in your line of thougths for the docs?
Some other ideas randomly stored there
The text was updated successfully, but these errors were encountered: