I am in complete agreement with your comments. And I know John remembers, I've been pushing for templates since we joined the apache-incubator. This has been met with what I now equate to a firm 'not at this time'.
So that leaves the responsibility on us to curate/manage/audit the wiki (which is part of owning a wiki to begin with). I there is anyone out there with Apache super hero powers that could make templates a reality, then most of these issues would go away. Here is what I'm asking for now: --At least a few of us draft a visual guideline. I am not proposing we enforce this on writers, what I am proposing is to start, I will walk the wiki and do my best to update content to the style guide. If people like the result, we can look at a more sustainable process of keeping the wiki visually cohesive. Any thoughts? -Kelcey >-----Original Message----- >From: Mark Hinkle [mailto:mark.hin...@citrix.com] >Sent: Friday, March 01, 2013 11:28 AM >To: cloudstack-marketing@incubator.apache.org >Subject: Re: Wiki visual guidlines > >+1 on the Wiki Template ;) > >I think the sentiment is right. The formatting is secondary to me. Above all the >documents themselves should be good but if they are hard to consume that's >almost as bad. > >My 2+ cents: > >I feel it's confusing that we have a wiki and manuals separate. IMHO >Documentation should help lead users to the right document. I am not sure at >what point to drop the Installation Guide and go to Admin or Developers for >instance. Also having all the links to the formats are great but it makes the >navigation confusing. > >This navigation experience is not great: >http://incubator.apache.org/cloudstack/docs/en-US/index.html > >The Docs are listed in the left frame but it's not clear what they are all for. As >Matt points out the end-user experience is better here: >http://docs.openstack.org/ > >Specifically, Once you get into the individual manuals the left side is pretty >useless the search doesn't appear to work either. I think that might be an >artifact of the Publican builds (points to a localhost >search)(Jira-1479) > >We also break out docs by release number but for release notes especially I >like to be able to view them on the same page to understand the scope of >release differences. > >Of course these are just my opinions. Also I should note that a lot of people >have done good work to get the documents this far you should have seen >them a year ago :P > > >Mark > > > > >On 3/1/13 10:43 AM, "John Kinsella" <j...@stratosec.co> wrote: > >>I concur with the general idea, but I have no expectations that >>engineers will follow a style guide unless it's amazingly easy to use. >> >>If only we could have a wiki templateŠ ;) >> >>My thought is we pretty things up, then Kelcey (and hopefully others) >>help keep things looking decent. In time hopefully folks will pick up >>on what we want and create new content that becomes close to the idealŠ >> >>John >> >>On Mar 1, 2013, at 10:07 AM, "Kelceydamage@bbits" <kel...@bbits.ca> >> wrote: >> >>> I'm glad people are voicing up on this. I brought it up because, >>>that's my primary business, websites/web apps, and to give you an >>>example the ratio of content artists to developers is 2.2:1. >>> >>> People make a decision in less then 30 seconds, not a lot of content >>>can be ready in that time, but a lot of visual and navigation can be >>>consumed in 30 seconds. >>> >>> The homepage and wiki is what we are marketing whether we believe it >>>or not. That's the first interaction, downloading and installing comes >>>later. >>> >>> Im hoping a few more people will chime in on this, >>> >>> I would like to get a broader sense of opinions before I take any >>>actions. >>> >>> Thanks. >>> >>> Sent from my iPhone >>> >>> On Mar 1, 2013, at 9:16 AM, Mathias Mullins >>><mathias.mull...@citrix.com> wrote: >>> >>>> Folks, >>>> >>>> I think you're are both right, and they both have to be done. It's >>>>harder, it's longer, but it's the right and best west way to do it. >>>>The two websites that I personally hate the most are the ones that >>>>have great content, and are hard to look at and use; or the ones that >>>>are beautiful and the content is useless. >>>> >>>> I've only been working with the project for about 6 months and I can >>>>tell you from an outsider's point of view that when I first came into >>>>it, even being a citrix employee, it was extremely unattractive. >>>> >>>> The Quality finally has got there, and Joe is right that MUST be >>>>maintained, but if you really want to grow this and get people to >>>>join, Ilya is right, you have to have to something attractive to lure >>>>them in and keep them. >>>> >>>> Look at Openstack's page. While the content may not be super flashy >>>>or techno-beautiful, every page has three key compents: >>>> 1. Content that matches the stated purpose of the page (Quality is >>>>in the eye of the beholder sometimes) 2. The navigation is easy and >>>>user friendly 3. Each page is consistent and high quality standards >>>>match on every single page. One logo, one font, one style sheet. >>>> >>>> Isn't this the level that we are really talking about taking this too? >>>> >>>> Thank you, >>>> Matt >>>> >>>> On Mar 1, 2013, at 11:56 AM, "Musayev, Ilya" >>>><imusa...@webmd.net<mailto:imusa...@webmd.net>> wrote: >>>> >>>> I think the *code* and *quality* of documentation mean a lot more >>>>than whether we have consistent colors and branding. Again - if we >>>>have anything that's just hideous to look upon in the wiki, we should >>>>certainly fix it. >>>> I'm all for quality of content and code, but we need to keep in mind >>>>that people tend to judge the book by its cover - especially the new >>>>comers. In comparison, the CS layout / usability is hands down one of >>>>the best and pleasant layouts I've worked with. Wiki - needs a little >>>>help - though as you said, should not be a high priority. >>>> >>>> >>>> >>>> >>> >> >>Stratosec - Secure Infrastructure as a Service >>o: 415.315.9385 >>@johnlkinsella >>
