Write content-edit.txt

Thanks Chris!

Can you make one more pass through this:

a) Remove all of the // comments from the template.

b) Remove the "Site Prerequisites" section, rather than saying "we don't need this".

c) After you took on this issue, we added some guidelines about screen shots. See:
https://userguide-drupal.redesign.devdrupal.org/guidelines/good-writing....
(section on "convey ... text and images")
So could you create a rough screenshot and follow the instructions to add it to the file?

d) We also added a guideline for 80-character-max lines and one for @todo (it should be lower-case @todo not @TODO).
https://userguide-drupal.redesign.devdrupal.org/guidelines/formatting.html

Thanks!

Looks good Chris!

I was going to commit this because it is pretty close and I think it is pretty much fine for the first patch... but I found one thing I couldn't quickly fix. So here's the full list of what I would like to see changed before this gets added to the Guide as the first pass:

a) (I just added this to the Template instructions): The "goal" section is supposed to be the goal for the *reader* not the goal for the *topic* or *writer*. Sorry that was unclear!

b) Can you wrap the lines at 80 characters max? That was also added to the guidelines recently.

c) One image has no instructions to regenerate.

d) One link starts with "link:" -- take that out. Should just be:

http://example.com[link text goes here]

e) This is the one I couldn't fix... there is a link that says:
<<_administering-blocks,Editing Blocks>>

AsciiDoc will not compile if there is a cross-link to something that doesn't exist. So... I am not sure what topic this is supposed to be? If it exists, use an actual topic ID (file name without the .txt suffix); if it doesn't exist yet, use a @todo.

f) Do not put indentation at the beginning of paragraphs. That actually does something specific in AsciiDoc like ... I think it is blockquotes or something. Talking about things like this:

  The other common way to locate a piece of content to edit is to click on the "Content"
button in the Admin menu bar to view a list of all the content on the site. You can and 
use the filters to locate the content you want to edit. 

That first line should not start out indented.

Thanks!

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

Thanks Chris -- and wow, that's a lot of writing!

So... I think that a lot of this is good information, but I'm not sure it belongs in this particular topic. All we really want to cover here is how to get to the Edit screen, I think. We should put the information on what values to put in the content create topic I think, and refer to it here?

Also, we have updated our guidelines on how to document how to fill out a form:

a) Make a screen shot
b) Make a table of values to fill in. See http://www.methods.co.nz/asciidoc/userguide.html#_tables

(See section 2.3.4 on https://userguide-drupal.redesign.devdrupal.org/guidelines/good-writing.... )

But really I don't think that all of this information belongs here. See #2513516: Write content-create.txt -- maybe you could collaborate with the person doing that topic and get this information in there?

Also, I don't think we want quite so much as that in the Prerequisites section. The topic should stand alone somewhat, but we don't need to include things like "basic web knowledge" which is a prereq for the book as a whole.

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. 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.

Thanks!

Here's the checklist for this stage (from https://userguide-drupal.redesign.devdrupal.org/guidelines/writing-editi... ):

- 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.)

So... To get this ready to pass this checklist, what we need:
- Screen shots and table for the form values (see comment #14 above)
- Remove everything that isn't supposed to be covered in this topic (see comments #14/#15).

Thanks!

Adding checklist to issue summary.

I got email from Chris and he's not able to complete this right now... so I finished it off. Thanks Chris for your efforts!

The text here looks good to me. And I think it's ready to be committed. Though I have a question. Neither this topic, or any other that I can find, seems to explain the ability to navigate to a page in the public facing part of your site, and click the edit link from there. So before we commit this I think we should decide to either address that in this topic, or to add a new topic for editing via the menu local tasks / tabs as that's a pretty common way for people to get at things in Drupal.

Review:

- Does it follow the template?

Yes

- Have the comments and placeholder text been removed from the template?

Yes

- Is everything the topic was supposed to cover included, and nothing extra?

Yes, see above ...

- If there are @todo notes, are they clear?

Yes

- 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.)

Yes

- Is attribution provided?

Yes

Good point. How about if we add a note about this in the Follow-on Tasks section of this topic, like this? I think we should also mention this from the in-place editing topic, so I'll add a note to the spreadsheet.

Note: The only section that is different in this text file is Follow-on tasks.

That works for me. I've gone ahead an committed this. Thanks Chris and Jennifer.