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?
Comment | File | Size | Author |
---|---|---|---|
#29 | structure-fields.txt | 5.89 KB | batigolix |
#20 | structure-fields.txt | 5.02 KB | batigolix |
#18 | structure-fields-add-field.png | 54.26 KB | batigolix |
#18 | structure-fields-vendor-url.png | 73.43 KB | batigolix |
#18 | structure-fields-main-img.png | 141.82 KB | batigolix |
Comments
Comment #1
Sree CreditAttribution: Sree as a volunteer commentedComment #2
jhodgdonAdding checklist to issue summary.
Comment #3
jhodgdon@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!
Comment #4
Sree CreditAttribution: Sree as a volunteer commentedHi @jhodgdon,
Yes, I am almost done with this. I will finetune it and would submit within a couple of days.
Thanks,
Sree
Comment #5
Sree CreditAttribution: Sree as a volunteer and at Sogeti, Capgemini commentedAttributions 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
Comment #6
jhodgdonLooks 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
Comment #7
ifrikComment #8
jhodgdon@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!
Comment #9
jhodgdonOne 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.
Comment #10
batigolixIll give this a shot
Comment #11
batigolixI 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.
Comment #12
batigolixComment #13
batigolixComment #14
jhodgdonThanks 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?
Comment #15
batigolixRegarding 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.
Comment #16
jhodgdonSounds like a plan.
Comment #17
batigolixHere'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"
Comment #18
batigolixComment #19
jhodgdonLooking 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!
Comment #20
batigolixNew 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
Comment #21
jhodgdonSorry 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!
Comment #22
jhodgdonComment #23
batigolixI unassign so someone can take over as I'm in a low contribution mode at the moment ;)
Comment #24
Sree CreditAttribution: Sree as a volunteer commentedWould continue on this again!
Comment #25
jhodgdonGreat, thanks! I think #20 version is a good starting point, see review in #21.
Comment #26
oseldman CreditAttribution: oseldman at Advomatic commentedJust 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.
Comment #27
jhodgdonAgreed, thanks for noticing that!
@Sree, are you still planning to continue with this topic?
Comment #28
jhodgdonUnassigning due to no response from Sree in 4 weeks... Sree -- if you still plan to continue, please let us know. Thanks!
Comment #29
batigolixI added an explanation column to each table. Please review.
Comment #30
jhodgdonGO 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!
Comment #31
jhodgdonThis looks great, thanks!
As per the review in #26 (thanks @oseldman!), we should change these lines to say 1 value:
Oh. Dang... I was going to just make these changes and commit it, but it's missing an image:
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!