Write user-new-role.txt

Standardize title

RE #8 - please write up an Attributions section. See the User guide project page for links to how to do that, and paste it into this issue as a comment.

A couple of other things to fix before we can add this to the project:

a) I think your starting point was not the user-new-role.txt file, because the ID at the top should be [[user-new-role]] and instead it is [[block-concept]] -- so please change that.

b) Remove all the // comment lines from the template (see instructions in the template). And the placeholder text.

c) Titles Of Topics Need To Be Title Case Not Sentence Case :) Also let's not put ("vendor") in the topic title, and start with an -ing verb.

d) Needs an index entry (see template instructions)

e) Oh... Actually it looks like you started with the Concept template instead of the Task template. So... My suggestion would be to find the actual user-new-role.txt file that is in the project, and put your text in there in the appropriate sections. The template you used doesn't have the right sections for a Task topic.

You can find the right file to start with at:
http://cgit.drupalcode.org/user_guide/tree/source/en/user-new-role.txt?h...
(Click the "Plain" link above the text of the file to download a plain-text version)

Unfortunately the airport WiFi where I am now is not letting me put this up on the Dev site we're using for the project but you can get it at that link and paste into the editor.
Thanks!

Ah, the WiFi came through. So if you go to the dev site I fixed the title and you can see which file to start with now. :)

https://userguide-drupal.redesign.devdrupal.org/d8guide/en/index.html
and click on the "Create a New User Role" link to view and then edit the file.

We decided to use separate issues for each phase of writing/editing.

Also before we can finalize this, we need an attributions block written for this; see project page for a link to how to do this.

Hi! Are you still working on this? Hopefully yes -- if not, please comment here and let us know we need to find someone else. And if you are, do you know when you might finish writing this topic?

By the way... there have been quite a few updates to our processes since the sprint where you took this on. For one thing, we have a more concise guide to contributing (with links to specific instructions) on the project page:
https://www.drupal.org/project/user_guide

Also, the templates and some guidelines have changed, especially in the area of screen shots and images.

And we've finally made a complete outline for the guide! See
https://userguide-drupal.redesign.devdrupal.org/d8guide/en/index.html
to find your topic, along with its new template.

Thanks!

We also put more notes about what each topic should cover in the tracking spreadsheet; see
https://docs.google.com/spreadsheets/d/1ov0FyJhKrJe7PYvohzV5UrrLyRaVCy2A...
for that.

Wonderful, thanks!

So we now have a checklist for the "write" stage on topics -- see
https://userguide-drupal.redesign.devdrupal.org/guidelines/writing-editi...

Checklist:
- Does it follow the template?
- Have the comments and placeholder text been removed from the template?
- Is everything the topic was supposed to cover included, and nothing extra?
- If there are @todo notes, are they clear?
- If there are images included, do they include instructions for how to redo them in a comment? (Note: Screenshots do not need to be perfect. Just make a rough cut.)

And in the tracking spreadsheet, your topic "covers" column says:

Create a Vendor role

So... taking a look at your file:

1. Template: check!

   Although it would be good if you could go back to the template and put in the missing sections as comments. For instance, you removed the "Site prerequisites" section, so rather than making it completely gone, it would be better to leave it as:

   //==== Site prerequisites

   in your file, so that we can see explicitly that it has been removed.

   You can see the template at:
   https://userguide-drupal.redesign.devdrupal.org/guidelines/writing-editi...

2. Comments removed: Mostly! There's one piece of placeholder text still in there:
   

   And it could be a couple of paragraphs.

3. Coverage... There is some extra information in there about what a role is. We're trying to keep task topics (such as this one) focused on the task, and leave concept information (like what a role is or why you should care about them) in the Concept topics. There's another topic in the outline, "Concept: Users, roles, and permissions" that covers "The relationship between users, roles, and permissions". So this topic should not include that information.

   I'm referring to:

   One of the most basic features of administering user Web Site permissions through Drupal is by the creation of roles.

   Rather than assigning individual permissions to each user, permissions are assigned to roles and roles are assigned to users. Using roles gives administrators greater control over permissions, and makes it easy to assign and remove roles when necessary.

   So we need to remove that.

   Also on coverage, I think it would be helpful to tell how to navigate through the menu/toolbar system to get to the permissions page (Click on People in the navigation bar, then Permissions) instead of just starting at the Permissions page.

4. @todos - none, fine!
5. images - great! Although did you make some rought images? Please attach them in the Files section to this issue.
6. And one more thing: We'll need the Attributions information too. See
   https://userguide-drupal.redesign.devdrupal.org/guidelines/guidelines.ht...
   for instructions.

So... just a few little things to take care of and we can add this to the guide. Thanks!

Adding checklist to summary. Still needs attribution information (see link in summary), and a bit more work.

@JackProbst: Are you interested in fixing the few things that were mentioned in comment #15, or should we find someone else to finish this up? Thanks!

I'll have a look at this

adding credits

I went through the list of remarks. I rephrased the text in several places, so it needs another review.

I made a couple of minor edits to the formatting of the text so that it conforms to our guidelines. I changed the language used to show how to navigate to a page so that it follows our standard:

eg.

In the _Manage_ administrative menu, navigate to _Structure_ > _Taxonomy_ (admin/structure/taxonomy).

And made sure that user interface text is marked up with tags.

Verified that file follows the checklist above, and that the issues are present. Looks good to me.

This has been committed. Thanks @JackProbst, and @batigolix