Section References and Order

cloudant-labs / slate

The Cloudant Documentation, built with Slate

Other

14 stars 17 forks source link

Section References and Order #8

Open bradley-holt opened 9 years ago

bradley-holt commented 9 years ago

Are "Cloudant Basics", "API Reference", "Client Libraries", and "Guides" proper nouns? Related, perhaps these should be hyperlinks. Also, the order of these is different in the opening paragraph than in the nav (not sure if this matters).

KimStebel commented 9 years ago

I'm not sure which part of the site you are referring to and what you want to change. A link might help.

bradley-holt commented 9 years ago

These are first referred to in the opening Documentation section. The order that these items are mentioned here appears to be a different order than the navigation bar along the left. The following changes should be considered:

Are these really proper nouns? If not, they should be listed as "Cloudant basics", "API reference", "client libraries", and "guides" instead.
Alternatively, hyperlink these to their respective sections (which subtly explains to the reader why they're mentioned as proper nouns).
Change the order in which these sections are listed in the opening paragraph to be the same order as these sections are listed in the navigation bar along the left.

bradnoble commented 9 years ago

This is an artifact of the project being in a halfway state. I agree that harmony here is better. I'd like the nav at left to dictate -- and ideally the nav at left presents the key elements in the order the user encounters them: Account, Databases, Documents...

Also note that we're right now presenting too many items in the side nav; we can limit those links by tweaking tocify to only show headings up to h2 or h3 or h4. I think it's set at h3 now, which is too many.

KimStebel commented 9 years ago

I agree about the order and changing to h2. Regarding the case, where we are using these phrases as titles or headings or are referring to these, the English language thankfully affords us a lot of flexibility, i.e. it's a matter of taste. See http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles