Community

[dneary]

I would have preferred a squashed commit here... the end result is the important thing.

This is modelled on what JM and myself came up with, and there are some lminks in here twice, since they're relevant both for users & developers. Working on several of the empty pages/dead links now.

[Fryguy]

US English uses the 'z': familiarize

[dneary]

Do you think we could commit this and integrate your changes in a different commit? Seems like a valuable addition and I really am not sure how to propose an alternative version. I agree with most of your changes.

[dneary]

Hmmm... just realised this change is now proposed twice - once on this branch, and once as a separate pull request. Clearly I'm still confused by this pull request thing... I should be reading the docs, not writing them ;-)

I did find this good answer (at least, it looked good to me) in Stack Overflow: http://stackoverflow.com/a/15055649/334301

[garrett]

Issues with the headers

I don't like the headers:

• Users and admins
• Developers

1. Firstly, how are admins different from people using ManageIQ? Isn't ManageIQ for people administrating systems?

2. Secondly, it's almost always a poor choice to refer to people as "users", for several reasons.

   It's dehumanizing and a derogatory word. It often doesn't define people properly either. Even worse: it's the oft-used term for a person on drugs.

   There has been much written on the subject; here's a good article on the topic: Words Matter. Talk About People: Not Customers, Not Consumers, Not Users. There's also Why Not a 'User'?.

   It's bad enough that terms "user" exist in our professional lexicon (even for designers: see UI & UX, for example as well as GUI, and so on…), but we should never, ever expose this terminology to people using the software.

3. Thirdly, the links aren't about the people who may use, administer, or develop the software, but are links for tasks that people may want to interact with the ManageIQ community and the software it produces. (The content is about things and actions, not about the people... where the headers are referring to the people doing those things.)

We can't say "People" and "Developers". So what do we say? (Continued below)

---

Rewording?

Well, we can turn around the headings and talk about the tasks people will be doing with the software.

• Using ManageIQ
• Developing ManageIQ

...but then it gets a bit wordy. Also, it's usually best to not have gerunds (those things that usually end in '-ing') in headlines.

• Use ManageIQ
• Develop ManageIQ

...like above, are both redundant, as this is on a site about ManageIQ.

"Use" and "Develop" are too short, and "use" isn't really what those links are about. Most everything in the "Use" section is actually about communication.

Rethinking the section split

It's really about communication.

• Follow on social media (communication)
• Talk on IRC (communication… but only for people developing, as previously discussed; the forum & Q&A sites are the place for people using the software)
• Report an issue (communication again here; valid for everyone who may use and/or develop the software)
• Answer an unanswered questions (communication: documentation (realtime) specifically)
• Propose a feature (communicate with the developer team)
• Document a task (communication: documentation)

So, really, we have competing things inside of the current "Users & Admins" section (more real-time communication and then communicating usage).

It might be better to split these currently-two sections into three sections: "Communicate", "Educate", and "Develop". (Educate could be "Document", but the goal with documentation is education, really. Educate is an obvious action word, where as "Document" could be interpreted as either a verb or a noun... but really, either could be fine.)

Summary: I suggest to split into "Communicate", "Educate", and "Develop".

---

Additionally

Also, it would be best to have the content displayed on this page in a different manner. Rather than simply lists of links; we should make it stand out more. This can be achieved by several different means, including text rewording and formatting or perhaps some graphical elements. (However, tossing graphics at something doesn't necessarily help and it also takes time.)

---

However... build upon

These changes are probably a little bit larger than this pull request. We already have too many things going on here. For example, when I will rewrite this commit to make it more acceptable to inclusion, I will be sure to split out the documentation on patches as a separate commit from the editing of the community front page.

Therefore, I think it's acceptable to merge in the patch with some minor edits (squash & split) and then, afterward, build on top of the commit with the suggestions I have made here.

[garrett]

I've manually merged in the changes as worked on in this branch as two different commits.

As such, the content has been merged as intended in this pull request, so I'm closing the issue.

[garrett]

Opened #62 for working on the content further.