[jira] [Created] (COUCHDB-3176) Docs front page has holes, link to TOC is obscure

["Joan Touzet (JIRA)" <ji...@apache.org>]

Joan Touzet created COUCHDB-3176:
------------------------------------

             Summary: Docs front page has holes, link to TOC is obscure
                 Key: COUCHDB-3176
                 URL: https://issues.apache.org/jira/browse/COUCHDB-3176
             Project: CouchDB
          Issue Type: Improvement
          Components: Documentation
            Reporter: Joan Touzet


This came up on IRC tonight:

{noformat}
02:36 < KB5> Okay, I can see why docs have holes in them and why the security
             concept is obscure. The problem is that table of contents is not
             visible on the docs page. On the docs page there are four main
             subjects, with various number of sub-topics under them. If you
             click on those and pay attention to subject numbering, you notice
             that they jump around. You don't actually get table of contents
             unless you click "Table of Contents" after opening one of the sub-topics.
02:37 < KB5> Basically, full docs are hidden from the casual viewer and this is
             something that should be corrected. It should be made clear that
             the subjects presented on the docs page is not full table of
             contents and actual link to table of contents should be more
             accessible.
{noformat}

I agree, this is something we should improve.

We started out highlighting specific topics on the home page but it's not possible to find everything this way. Either we explicitly call out the top level page's listings as "promoted sections," we convert the home page to a full TOC, we promote the TOC link at the top of the home page, or some combination of the above three.

Other ideas welcome, if no one posts anything in a week or so I'll try my hand at a new top level page myself.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)