[
https://issues.apache.org/jira/browse/QUARKS-104?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15230420#comment-15230420
]
Julia Bamford commented on QUARKS-104:
--------------------------------------
Hi Queenie,
I just want to make sure I understand what changes you are proposing.
1. Remove the numbering of subsections.
Do you mean from the table of contents? I wonder if Will used the numbering to
control the order in which files were displayed. If it's merely cosmetic, I'm
fine with removing the numbers. But if the numbers actually control the display
order then we should leave them. It's important that the docs stay in order.
2. Commit to using title case capitalization
The more modern style is to use sentence style capitalization rather than
headline style (which you suggested). However, it does make it imperative that
everyone identify proper nouns (or programming terms) that must be capitalized.
Headline style is probably easier but sentence style is more modern.
I don't have strong feelings about this one, but I do want to make sure we're
aware of the trade-offs.
3. Redundant headers should be removed.
Agreed.
4. Page headers should start at level 2 using ## in order to have them added to
the Table of Contents.
I think that's fine. My only question is how do the section headings in the TOC
get generated?
> Documentation website consistency improvements
> ----------------------------------------------
>
> Key: QUARKS-104
> URL: https://issues.apache.org/jira/browse/QUARKS-104
> Project: Quarks
> Issue Type: Improvement
> Components: Web Site
> Reporter: Queenie Ma
> Priority: Minor
>
> Some parts of the documentation site are inconsistent with each other, such
> as capitalization and differences between the sidebar titles and page titles.
> Possible improvements:
> # Remove the numbering of subsections (i.e., "Get Started", "Sample
> Programs", "Using The Console")
> # Commit to using title case capitalization (i.e., all words capitalized,
> except for minor words such as 'the', 'of', 'to', etc.) for sidebar/page
> titles and sentence case capitalization (i.e., first word capitalized) for
> page headers
> # Redundant headers should be removed (e.g., see [Common Quarks
> Operations|http://quarks.incubator.apache.org/docs/common-quarks-operations.html])
> # Page headers should start at level 2 using ## in order to have them
> added to the Table of Contents.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
