Title: Adding Basic Fields to a Content Type
Section: Setting Up Content Structure
File name: structure-fields.txt
Covers: Prereq knowledge: Types of Content. Add fields for "Main Image" and "Vendor URL" to the Vendor content type. Follow-on task: Add the same Main Image field to the Recipe content type; create Vendor content items. Note multilingual settings.

Attribution

See https://userguide_new-drupal.dev.devdrupal.org/guidelines/guidelines.htm...
[Fill in!]

<<structure-fields>>::
  Written by https://www.drupal.org/u/sree[Sree Veturi] and https://www.drupal.org/u/batigolix[Boris Doesborg]

Checklist for this phase

- 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.)
- Is attribution provided?

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Sree’s picture

Assigned: Unassigned » Sree
jhodgdon’s picture

Issue summary: View changes

Adding checklist to issue summary.

jhodgdon’s picture

@Sree - Are you still planning to write this topic? If so, do you have a time frame? If not, please unassign the issue so someone else can work on it. Thanks!

Sree’s picture

Hi @jhodgdon,
Yes, I am almost done with this. I will finetune it and would submit within a couple of days.

Thanks,
Sree

Sree’s picture

Attributions information:
Written by https://www.drupal.org/u/sree[Sree Veturi]

Checklist for this phase
- 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? No extras
- If there are @todo notes, are they clear? None
- 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

jhodgdon’s picture

Status: Needs review » Needs work

Looks pretty good!

A few things to fix up before we add this to the guide:

a) It could use some additional index entries, but we can take care of that in the Guidelines Edit phase too, so don't worry too much about it, but if you want to fix it, that would be wonderful.

b) We also have a standard way to describe navigation
https://userguide-drupal.redesign.devdrupal.org/guidelines/text-conventi...
which we can also take care of in the Guidelines edit phase, so again don't worry too much about this, but if you want to fix it, that would be wonderful.

c) When describing how to fill in a form, we want to have an image and a table. See:
https://userguide-drupal.redesign.devdrupal.org/guidelines/good-writing....
So I think many of the steps here can be consolidated into tables.

d) In general the tone of the writing is very conversational... which seems very pleasant, but we really want it to be concise instead. You might take a look at these other topics, which have a very clear and concise tone instead of being so conversational:
https://userguide-drupal.redesign.devdrupal.org/d8guide/en/menu-link-fro...
https://userguide-drupal.redesign.devdrupal.org/d8guide/en/content-edit....

And you might also read this section of the Drupal.org documentation style guide:
https://www.drupal.org/style-guide/content#voice

ifrik’s picture

Issue tags: +Barcelona2015
jhodgdon’s picture

@Sree - I'm hoping you would like to make the requested revisions and finish this off? If not, please add a comment here and someone else can work on it. Thanks!

jhodgdon’s picture

Issue summary: View changes

One other thing. I went to
http://cgit.drupalcode.org/user_guide/tree/assets/text.txt?h=8.0.x
and reminded myself that the two fields added on Vendor should be called:
Main Image
Vendor URL

Updating summary.

batigolix’s picture

Assigned: Sree » batigolix

Ill give this a shot

batigolix’s picture

Status: Needs work » Needs review
FileSize
7.98 KB

I went through the feedback from #6 and updated the topic.

Unfortunately by moving most of the steps text to tables I almost completely changed the original text . My apologies for that

The original had many images, and I'm not sure we need all of them. This probably needs a bit of discussion.

batigolix’s picture

Issue summary: View changes
batigolix’s picture

Issue summary: View changes
jhodgdon’s picture

Status: Needs review » Needs work

Thanks for the update! Yeah, the text looks pretty good now, and I agree most of the images are not needed...

Let's see. I think we should cut out most of the images, and rearrange slightly... Some ideas:

a) structure-content-type-Add-Field-link.png seems like a good image to keep, but it's not in the right place in the text for what the image shows. It shows you choosing to add a new Link field from the Add Field page, so it belongs after the first line of step 2. It's much lower down.

b) Then I would split out "Fill in the fields as shown below." in step 2 into a new step (with the table of fields), and that would go with structure-content-type-link.png

c) Then what is currently step 3 goes with structure-content-type-link-settings.png -- but it would be better if it had the correct values in it.

d) Then what is currently step 4 goes with structure-content-type-link-landing.png except it would be preferable if the values were filled out as in the table.

e) And by the way, all of these image files have the wrong name too. They should all start with structure-fields not structure-content-type.

f) Now on to the Image stuff. I think in current step 5, the part about the Image field should be moved to 6, and I don't think we need an image for 5, although I guess the confirmation image is good.

g) I think for step 6 (as currently numbered), we can do without a new image, since we already did one Add Field.

h) Step 7 should probably have structure-content-type-image-setting.png

i) Step 8 should have structure-content-type-image-landing.png but better if it had the values filled out.

Also in step 8 normally we put the explanations into the table of values to fill out? And this is actually misleading:
"By providing a File directory value you ensure that all the uploaded Vendor images will be located in the same folder.". The reason to provide a file directory is to separate this field's images from other images. Otherwise all fields' images will be lumped together in the same directory.

j) In follow-on... see "Covers" in the issue summary:
Follow-on task: Add the same Main Image field to the Recipe content type
and also
Note multilingual settings.
(for multilingual you could point them to the language-content-config page, and say that if they add a new field to an existing translated content type, they may need to revisit the language settings)

k) I also wonder about the related topics area... maybe in Follow-on we should point them to a few of the other field-related tasks, like adding reference fields, taxonomy fields; setting up forms and displays? But maybe not all of those, there are lots of things they could do.

Anyway, normally we would want tasks to be in Follow-on tasks and "related topics" to point mostly to concepts. And any concepts they need to know before doing this task should have been in Prereq Knowlege at the beginning, not at the end in Related.

The list of what's here seems kind of arbitrary too. Like image styles are not going to help them if they don't also do Manage Display. So I guess the thing to do would be to point them to structure-form-editing and structure-content-display as extra bullet items in Follow-on (in addition to (j) above). And then maybe we do not need Related Topics?

batigolix’s picture

Regarding the images: I'm going to do some of them again and add them where it seems useful to me, without trying to save previous work. So I will ignore your remarks about the images and focus on your remarks about the text.

jhodgdon’s picture

Sounds like a plan.

batigolix’s picture

Status: Needs work » Needs review
FileSize
5.04 KB

Here's a new attempt. As mentioned I did the images as I saw fit.

I addressed everything after point i) starting from "Also in step 8 normally we put the explanations"

batigolix’s picture

jhodgdon’s picture

Status: Needs review » Needs work

Looking pretty good -- much improved. Thanks for working on this!

A few notes:

a) Prerequisites - this *is* structure-fields, so we shouldn't require knowledge of structure-fields here. ;) Also structure-image-styles is a later topic, so we shouldn't require knowledge of that either. I would say that should go in follow-on tasks instead.

b) In tables of fields/values, don't we normally have a column with some explanation of the fields? Maybe that isn't necessary here, but ... maybe it would be helpful?

c) I almost never make fields like Vendor URL required when I'm building a site for a client. What if the vendor doesn't have a web site (which might be common for a farmers market, where some vendors just have a small farm and just sell at this market)? Also, you can't save even a "draft" version of the content item without all required fields being entered, so unless the site design would break without a field, I normally would leave fields as not Required. Thoughts?

Other than those small items, this is looking great!

batigolix’s picture

Status: Needs work » Needs review
FileSize
5.02 KB

New version.

Regarding your feedback:

a) That is done

b) I can see that some topic have explanations in the table (config-basic for example), but in the topics i wrote i only did a label and value column. As we are following a scenario I think it is OK, simple and straightforward to tell the reader what to enter. He probably wont follow the scenario exactly, but I think the combination of label and value is pretty clear. An field explanation may often result in a repetition of the field label or an attempt to say the same in different words ... dont know. Your thoughts?

c) Slightly similar to b): the reader will learn from the scenario. We can assume that he doesnt actually follow the scenario exactly. But , checking a required field is more interesting then leaving the default value and ignoring the field. Anyhow: I made one field optional and the other required ... Let me know what you think of it

jhodgdon’s picture

Status: Needs review » Needs work

Sorry for the delay in reviewing this -- I went away for a few weeks and this got forgotten.

So regarding point (b)/(c), This is precisely why I think it makes sense to add the "explanation" column. So for the Required checkbox, for instance, you can explain what the consequences of checking or not checking it are and explain why you probably don't want to check it unless your page design will totally break without the field being filled in. This is more informational than just checking Required on one instance, and not checking it on the other... yes we have a scenario, but they're supposed to eventually be able to generalize to their own site, right?

I agree though that for the simple forms, like Add new field, we may not need an Explanation column.

So... other than that, I think this is looking really good!

jhodgdon’s picture

Issue summary: View changes
batigolix’s picture

Assigned: batigolix » Unassigned

I unassign so someone can take over as I'm in a low contribution mode at the moment ;)

Sree’s picture

Assigned: Unassigned » Sree

Would continue on this again!

jhodgdon’s picture

Great, thanks! I think #20 version is a good starting point, see review in #21.

oseldman’s picture

Version: » 8.x-0.x-dev

Just a note: when reviewing this for creating a view based on this content type, I noticed that Step 4 has the "number of allowed values" for the Vendor URL set to 2. This doesn't seems to make sense, at least without further explanation.

jhodgdon’s picture

Agreed, thanks for noticing that!

@Sree, are you still planning to continue with this topic?

jhodgdon’s picture

Assigned: Sree » Unassigned

Unassigning due to no response from Sree in 4 weeks... Sree -- if you still plan to continue, please let us know. Thanks!

batigolix’s picture

Assigned: Unassigned » batigolix
Status: Needs work » Needs review
Issue tags: -Barcelona2015
FileSize
5.89 KB

I added an explanation column to each table. Please review.

jhodgdon’s picture

GO BORIS! I am a bit behind on User Guide, but will make some time tomorrow to review/commit (hopefully) this topic and the other two you've submitted in the last two days. THANKS!

jhodgdon’s picture

Status: Needs review » Fixed

This looks great, thanks!

As per the review in #26 (thanks @oseldman!), we should change these lines to say 1 value:

| Allowed number of values | The number of values that can be entered | Limited, 2
...
| Help text | The instruction that is shown below the field | Enter one or two URLs for the website(s) of the vendor.

Oh. Dang... I was going to just make these changes and commit it, but it's missing an image:

// To create this screenshot, add an image and a URL field to the vendor content type and fill in the fields shown in the tables above.
image:images/structure-fields-result.png["Field settings page",width="100%"]

Oh, good. Sree had made one for that:
https://www.drupal.org/files/issues/structure-content-type-image-confirm...
I put that in and renamed it.

So. Made that one edit and added to the guide! Thanks!

  • jhodgdon committed 961dcb8 on
    Issue #2541704 by Sree, batigolix: Write structure-fields.txt
    

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.