Docs experience for first-time users

cc @kushalpandya

@awhildy I agree, the docs are probably pretty threatening to users when they first see them. It'd be nice to have the sections of each product denoted with graphics or something.

The problem right now is that we need to have docs that work in both the Rails app's Help section and the Nanoc site at docs.gitlab.com. This limits what we can do with the homepages of each Docs product significantly.

Any ideas @axil?

Is there momentum around moving away from the Rails app's Help section (https://gitlab.com/gitlab-org/gitlab-ce/issues/18739) or is that another thing?

@awhildy there is, but Versions need to be added first and there are a couple drawbacks to flat-out removing the Help section.

@awhildy thanks for opening this

I couldn't agree more! In addition, we have many links buried inside other links inside other links and that makes discoverability a total pain. What we could do:

Provide more detailed index pages. For example, the main page of CE doesn't provide a word about what GitLab is, like you said is just a list of links https://docs.gitlab.com/ce/README.html. What we could do: in the main README page, mention what GitLab is, what the docs cover and then have 3 main areas: user guide, administration guide, developer guide. Each of these can have a little graphic of its own and then a link to the indexes: user/index.md, administration/index.md, development/index.md. For example, I tried to be more comprehensive when I wrote the Runner's index page https://docs.gitlab.com/runner/.
Make the landing page more pretty and targeted. I keep mentioning the kong docs over and over again, since I believe they are pretty and simple to navigate. Just see their landing docs page https://getkong.org/docs/. Also see a list of landing pages in https://gitlab.com/gitlab-com/gitlab-docs/issues/52.

It'd be nice to have the sections of each product denoted with graphics or something.

That we could do even in Markdown I believe :) I really want us to start using all the pretty graphics the UX team makes in the docs.

Sounds like a great plan @axil! I've added the steps for your first bullet point to the issue description. For your second bullet point, what do you mean by landing page? http://docs.gitlab.com/? Or something else? And by more targeted, do you mean a different split than by product? Like Kong docs seems to be split up by task (what a person might be trying to do)?

@hazelyang: Would you be able to help out with this? It would be awesome to have a graphic for each of the 3 main sections of docs (User guide, Administration guide, and Developer guide). This would be lower priority than making sure we are on track for work scheduled for the 8.15 release, but if you have some free time, help would be awesome. Let me know. Thanks!

@axil: Just reread #52, and I understand what you mean by landing page/home page. Makes sense! I'll see what we can do

Mentioned in issue #52

@awhildy Will do!

Reassigned to @hazelyang

@hazelyang looking forward to it!

mentioned in issue www-gitlab-com#977 (closed)

User documentation

I just wonder maybe we can move the description under the link.

Administrator documentation

Contributor documentation

I don't know where I am when visiting the CE documentation or EE documentation. I think if the title can be "Community Edtion" instead of "Documentation" would be better.

Illustration for CE documentation

Illustration for EE documentation

@hazelyang where can I find those great images? :)

@connorshea </br> seems to work... only on docs.gitlab.com.

@axil I put them in /gitlab-design/production/_assets/gitlab-doc. If you want to find the Sketch file, I pushed it to /gitlab-design/progress/hazel/gitlab-doc/.