cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Brooks <mich...@michaelbrooks.ca>
Subject Re: [website] Documentation Linkage
Date Mon, 04 Mar 2013 22:50:09 GMT
Hi Marcel,

As far as I know, we don't have any UX contributors, but the Adobe
contributors have access to a couple great UX minds.

Q1: Would you like me to perform the changes you've described below?


It looks like this has already been moved back under Developer and
reworded. Thanks!

 Q2: I did add a step to http://wiki.apache.org/cordova/CuttingReleases ,
> was that the wrong place?


Hmmm... the cutting a release article includes updating the docs and
website, but doesn't explain how. The "how" is documented in the website's
README.md [1]. I'll update the Wiki to reference the README.md for the
complete update steps.

Q3: In the future if I have ideas of similar magnitude for the website,
> those should be floated in a Jira item first?


I think the same mentality to code can be applied to the website. Trivial
changes (grammer, spelling, etc) can just be updated. Larger tasks like new
content, refactors (shifting content around, terminology changes), and
changes to process (steps involved to update) should be tracked on JIRA or
the mailing list.

I felt like a total ass nitpicking these details. I'm glad to hear it's
actually worked out a few areas of confusion.

Michael

[1] https://svn.apache.org/repos/asf/cordova/site/README.md

On Mon, Feb 25, 2013 at 10:19 AM, Marcel Kinard <cmarcelk@gmail.com> wrote:

> Those are all from me.
>
> I am all for high-quality user-facing resources, and that was the
> intention. I wasn't aware that there was access to UX skills, and didn't
> intend to do anything outside of protocol.
>
> Q1: Would you like me to perform the changes you've described below?
>
> Q2: I did add a step to http://wiki.apache.org/cordova/CuttingReleases ,
> was that the wrong place?
>
> Q3: In the future if I have ideas of similar magnitude for the website,
> those should be floated in a Jira item first?
>
> For full disclosure, I made other changes to the website over time,
> including a reference to the issues mailing list, added a paragraph
> regarding the docs, added links to the completed CLAs, added link to the
> download archive, etc. So please sanity check the whole page to see if
> there is anything additional outside of expectations.
>
> I'm cool with nitpicking, I want the user experience to be really good.
>
> -- Marcel Kinard
>
> On Feb 22, 2013, at 6:50 PM, Michael Brooks <michael@michaelbrooks.ca>
> wrote:
>
> > 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
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message