Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (nike.apache.org: domain of mikeywbrooks@gmail.com
 designates 74.125.82.49 as permitted sender)
MIME-Version: 1.0
Sender: mikeywbrooks@gmail.com
Date: Fri, 22 Feb 2013 15:50:42 -0800
Message-ID: 
 <CAP7NMPoiK-+YASGJ587-7X2OnAazQS_oVp9dpc5937wYLXGYng@mail.gmail.com>
Subject: [website] Documentation Linkage
From: Michael Brooks <michael@michaelbrooks.ca>
To: dev@cordova.apache.org
Content-Type: multipart/alternative; boundary=f46d04428eb6fcae6504d658dbb6

--f46d04428eb6fcae6504d658dbb6
Content-Type: text/plain; charset=ISO-8859-1

Hi all,

TLDR; Please avoid drive-by updates without documentation and/or discussion.

I feel like a nitpicker, but this is what leads to broken links and
low-quality user-facing resources.

1. Recently, there was a commit that reworded "Documentation" to "Cordova
Documentation"
    - I feel that mentioning "Cordova" is unnecessary.
    - I spoke with our UX team member and he agrees, summarizing the
reasoning as:
        - "Always remove redundancy."
    - I would like to change the wording back to "Documentation."

2. Recently, there was a commit that moved "Documentation" from the
"Development" category to "General"
    - Again, I think this is incorrect.
    - The Documentation is targeted at Cordova developers.
    - The "General" is a catch all bucket.
    - Our UX team member summarized this as:
        - "Always lean towards specificity or generality."
    - I would like to move Documentation back under "Development"

3. Recently, there was a commit that updated the Documentation link from "
http://docs.cordova.io" to "http://cordova.apache.org/docs/en/2.4.0/"
    - I understand why we may want to use the official URL.
    - However, the documentation is linked in multiple places meaning each
release we need to remember to update every mention of the documentation.
    - Additionally, the commit did not update the README.md's "How to
updating the docs" section with the new steps.
    - I'm fine keeping the URL as the official one, but please.... update
the README.md.

Let me know if you in agreement or against each of the points.

Thanks,
Michael

--f46d04428eb6fcae6504d658dbb6--