Update Field UI docs

Tagging "Fields in Core"

The UI itself needs to clarify these things, as well as the documentation--especially around separating "field settings" and "field instance settings".

added doc7 tag

I've written a new draft of the documentation based on my understanding of Fields UI. I'm not sure if this is case where it's okay to go beyond the recommendations for embedded module documentation since, as webchick says, it's a little hefty. This is my first time touching core documentation, so I'm sure they'll be problems with it, but it's a start. If I'm off-base and need to stick more closely to the standard, I'll rework it. Just seems like a lot of information to cover in two paragraphs.

To get a more thorough review from the doc team, please attach a screen shot of the help screen after applying your patch. Thanks!

Also tagging.

The patch needs a bit of reformatting -- rather than doing three P elements within a DD, just use three DD elements.

There is also some wording, capitalizating consistency, etc. that needs to be addressed -- we are not capitalizing things like Widget and Label, and please proofread your text (e.g. "need to determine whether the field type will contain (text, numbers, lists" needs to have the parens removed or else whether -> what).

Also... Does the word "widget" appear anywhere in the UI? If not, then let's not put it in the help screen. Same with "bundle".

And keep in mind that the help text you are editing is not going to be shown on the Manage Fields page -- it's in its own separate help screen. So it needs to stand alone and give an overview of what the module does, not details of how to do things.

i agree with @jhodgdon's feedback... also:
- fyi, yes widget is real (see: http://skitch.com/arianek/nm7ax/article-localhost.drupal7), but not bundle (as far as i know)
- and for reference, the help page standard is posted here: http://drupal.org/node/632280 and some general docs guidelines (for things like caps, etc.): http://drupal.org/node/338208

Thanks for the feedback. I'll post back with an update some time over the holidays, hopefully.

As for "bundle", it's true that it's not in the UI, but it's my understand that it's the (possibly emerging) general term for "stuff that can have fields". Are we going to assume, for the purpose of this help doc, that the only people seeing it are those will be adding fields to nodes? I assume this will be the most common use case (probably by a long shot), but still feel like the other cases should at least be mentioned as possible.

You can mention the other cases if there is a UI for adding fields to them (e.g. I think there is for Taxonomy, but not for User, but I'm not sure about that). But calling those use cases "bundles" in this help screen is not a good idea, because that term is not used anywhere and it's not highly intuitive (at least not to me).

Again, keep in mind that for the main help screen for a module, the idea is to give an overview of what the module can do, and to explain the core concepts of the module, rather than giving all the step-by-step details of how to do things. You can check out some of the other help screens now checked into Drupal core (or the current version of the Field UI help screen) to get a feel for the level of detail we're looking for.

Subscribinating

Okay, here's an updated version, attached as a screenshot as requested. I'm not including a patch this time, but I will once it's been fully cooked. I've reread the standards and tried to do a better job of following them. I've also tried to remove some of the how-to stuff that probably belongs on the online handbook page, while still providing what webchick was looking for.

Waiting to rewrite this meant that the UI for taxonomy and user accounts is now exposed. It looks like the UI for comments hasn't happened yet. Anyone know if that's going to happen?

#537750: Field UI for comments

Thanks for pointing that out. Screenshot updated.

Comments... This is a good start but it needs some work.

-- About
- If someone uses the Expert install profile, they do not get the "core Article content type". So please do not call it "core". You could say something like "The Article content type created by the Default install profile...".
- Please do not remove the link that is currently there to the Field module main help page.

-- Uses / Adding to content types
- Again, Article and Page are only defined if you use the Default install profile, so please don't assume people have them.
- I prefer saying "can" vs. "may". We don't like to talk about giving people permission to do things, but about what they are able to do.
- "as well as" in the first paragraph should probably just be "and".
- Second paragraph has too many commas.
- It took me several reads of the 3rd paragraph to figure out what it was trying to say. Needs a rewrite to be obvious on first reading.

-- Uses / Planning
- "the field itself" -- this should be called the field type (that is what it is called in the UI). "what the field will contain" should be "what data the field will contain" (this is also on the UI).
- 2nd paragraph in this section is a bit confusing and needs rewording.
- I think the whole section might be better as a bullet list or a DL list, where you could list the items you need to plan for and define. As it is now, these items are scattered around through the paragraphs, and the grammar/construction is different in each paragraph, so it doesn't make a coherent whole -- it just looks like some random suggestions.

-- Uses / Adding to content types
- You cannot actually edit or delete the Title field that is added by default.
- It appears that the title and body are added by default. Period. So probably you don't need to say that "some" fields are added by default, "such as" title and body, when you create a content type. Or is this subject to change in some way?
- You don't actually manage fields from Content Types, but from the edit a content type page.
- The help text should not go into so much detail about where the global/local settings are presented on the screen. (see comment #9 above). Besides which, this comment applies to when you define new content types as well.

-- Uses / Adding to users/comments/taxonomy
- These are much less detailed than the Add to Content Types section. So presumably they are drawing upon some information in the content types section? If so, the shared information should be presented in a separate section.
- Taxonomy section has no link to the taxonomy management page(s) where you would go to add fields, the way all the other "add to" sections have links.
- Please use parallel language for all the "add to" sections. For instance, the "comments" section says "Edit any comment type, and the "comments field" tab will be available", but the other sections don't word it like that. Comments should not either. See #9 above - we're not giving instructions, we're telling about what the module is capable of doing. Suggested wording would be "Comment fields can be managed from the Content Type editing screen", or something like that.
- Adding fields for Users is on the Manage Fields tab of Account Settings, not directly on Account Settings. Same for Taxonomy. This should probably be mentioned.

ps: Please attach both a patch and a screen shot next time. It would have been a lot quicker for me to edit and create a new patch than to make all of those comments. Thanks!

I've made some changes, but need more clarification before I post back with a patch. If I didn't include it here, it means I agree or at least understand what I need to work on.

-- Uses / Adding to content types
- It appears that the title and body are added by default. Period. So probably you don't need to say that "some" fields are added by default, "such as" title and body, when you create a content type. Or is this subject to change in some way?

Not quite. The Article content type also provides an image field and a taxonomy tags field. I assume that the fields provided aren't necessarily subject to change for the release of Drupal 7, but I don't know that for sure. I'm also thinking about people installing Drupal using install profiles other than the two provided with core. For those reasons, I didn't want to get any more specific. Is that acceptable?

-- Uses / Adding to users/comments/taxonomy
- These are much less detailed than the Add to Content Types section. So presumably they are drawing upon some information in the content types section? If so, the shared information should be presented in a separate section.

I admit I'm assuming that adding fields to content types will be the most common use case, so I concentrated on that. Poor assumption, apparently. I'll change it so there's a shared section first, with brief sections on the other things below. Content types will end up having a shorter section like what's there for comments, taxonomy, and users. Good?

- You don't actually manage fields from Content Types, but from the edit a content type page.

- Taxonomy section has no link to the taxonomy management page(s) where you would go to add fields, the way all the other "add to" sections have links.

- Adding fields for Users is on the Manage Fields tab of Account Settings, not directly on Account Settings. Same for Taxonomy. This should probably be mentioned.

The page title where user fields are edited is "Account settings", which is why I referred to it that way. The guidelines didn't seem to cover how to refer to tabs, so I went with the page title. This will affect any of these areas, so please give me the canonical way of referring to each of these locations. That is, how exactly to refer to the location where fields are edited for content types, taxonomy, comments, and users. Here are my guesses:

- the manage fields page of a [content type](admin/structure/types)
- the comments fields page of a [content type](admin/structure/types)
(this seems problematic because you can't see that it exists until you click one of the links that's visible on the content types page)
- the manage fields page of [account settings](admin/config/people/accounts)
- the manage fields page of a [taxonomy vocabulary](admin/structure/taxonomy)

Please correct these as needed.

Still better to post your incomplete patch together with your questions. Allows others to directly improve the patch, instead of writing down what you should write in the patch. See the double work there? :)

I don't know about the rest of you, but I find writing documentation in the module to be kind of a pain and generating the patch afterward. But I see that's not a good idea, so I'll post the patch in a little bit. If anyone can answer my questions in the meantime, that would be great just so I know.

Here's a patch.

Sorry, messed up the tabbing. This is the real patch.

And here's a screenshot. I was having trouble uploading it at the same time as the patch (timed out for some reason), so I'm trying it separately.

Your latest patch still has some problems... For one thing, it doesn't apply because of this:

--- /Users/chellman/Desktop/field_ui_orig.module	2010-01-29 22:14:17.000000000 -0600
+++ /Users/chellman/Sites/drupal-cvs/modules/field_ui/field_ui.module	2010-02-02 11:43:30.000000000 -0600

You need to use cvs diff to create patches. There's some documentation somewhere... let's see... http://drupal.org/patch/create

Anyway, rather than describing the text changes I would suggest, I'll just create a new patch.

You need to use cvs diff to create patches.

That very page you're referencing says that diff is a perfectly fine tool for creating patches, and it's what I always use (and it works). I should have cleaned up those paths at the beginning, though, I'll freely admit that.

I know you're creating a new one, but if it's any help (since this was 15 minutes ago), I've fixed the paths on the attached patch.

Here's a new patch. It gets this help page closer to standards established on other pages, cleans up a bit, etc. See screen shot.

Looks good to me, except for this sentence in the introduction:

"Fields can store various types of data, and the each type of data has a field type associated with it."

That feels a little unclear, maybe because the word "type" appears so many times. I think it might be fine just to leave this sentence out.

Other than that, works fine for me.

I also think this sentence is a bit confusing.
FWIW, I've always find the notion of 'field type' to be better understood when actual examples are given : text, number, file, image... Gives a more concrete turn on the whole topic discussed in the page.

Good catch, that sentence definitely had a typo in it...

How about this for the About section:

The Field UI module provides an administrative user interface (UI) for attaching and managing custom fields on content types, taxonomy vocabularies, user accounts, comments, and other data. Field types (text, image, number, etc.) are defined by other modules, and collected and managed by the Field module. For more information, see the online handbook entry for Field UI module.

Here's a patch. Screen shot as in #25, except the About section has been changed to the above.

- Oops, just noticed :
"managing custom fields on content types, taxonomy vocabularies, user accounts, comments, and other data"
There's an inconsistency here (taking the list in reverse order to make the inconsistency clearer) :
Fields are attached to comments (by content type), users accounts, taxonomy *terms* (by vocabulary) and content (by content type).
The list mixes objects and bundles.

The "and other data" is a bit vague/confusing. Maybe the list could just end with a dot, and the heading could mention that some contrib modules will enable more field types, or add other kinds of data that are able to have fields attached ?

The distinction on taxonomy terms vs vocabularies also applies to the "Adding fields to taxonomy vocabularies" section.

- Also, note that those fields we're managing are not necessarily 'custom' (added by the user) : some are automatically added by the code in some modules (e.g node and comment body), some of them are even hardcoded (as in : can't remove them through the Field UI - no example in core, though).
I'll leave you guys decide whether that 'custom' is misleading enough that it's better removed.

- The "Reusing custom fields" section is quite good IMO, this is often tough to explain.
FWIW, the main reason for sharing a field is not to reuse some field settings, but rather to let Views see it as only one dataset across different bundles: give me all the nodes having this value in this field, whatever the node type. I'm aware that it's tough to explain in a core help page :-(, but it's actually the reason.

The list mixes objects and bundles.

The text certainly glosses over a lot of detail, but I've been assuming that we're trying to get a general descriptive idea across, as opposed to a rigorous technical overview (also avoiding a prescriptive "how to do stuff" approach). The term bundles was stripped out earlier for that reason, at least in part.

The "and other data" is a bit vague/confusing.

I think it's vague on purpose because the possibilities in contrib are many, so just noting that other possibilities exist is enough. Is it acceptable to mention contrib stuff in these help files? I've been thinking it's not up until now.

The distinction on taxonomy terms vs vocabularies also applies to the "Adding fields to taxonomy vocabularies" section.

In the user interface, fields are added at the vocabulary level, so that's why it was expressed that way. They appear on terms, but you can't add unique fields to an individual term. I don't know if it's problematic to express it this way, but that's the idea.

I'll leave you guys decide whether that 'custom' is misleading enough that it's better removed.

My vote is no, it's not confusing enough to remove. I take custom to mean "anything not provided by core somehow", which seems safe for this use.

Thanks for the clarification on why fields are reusable. I mean, what the help says is also true (right?), but it's good to know a more robust, general reason.

Agreed that "bundles" should be left out of this help text.
Saying that fields can be added to taxo vocabs is simply incorrect though. What matters is that you get fields on your terms, not on your vocabs.
After that, the "Managing fields on terms" section can expand that it is done on a vocab by vocab basis, and happens in the admin pages for the vocabs - if that helps, "just like adding terms to content is done on the content type admin pages".

I think it's vague on purpose because the possibilities in contrib are many, so just noting that other possibilities exist is enough. Is it acceptable to mention contrib stuff in these help files? I've been thinking it's not up until now

Well, IMO mentioning contrib is better than a forced vagueness to avoid mentioning it. I don't see why core help text should pretend core is alone and contrib doesn't not exist, that would be just untrue.

I take custom to mean "anything not provided by core somehow"

Precisely : comment and node body fields are provided by core :-)

We add fields to content types, and they show up when you add an item of that content type.
We add fields to taxonomy vocabularies, and they show up when you add a term to that vocabulary.
It's parallel. If you want to say we are adding fields to taxonomy terms, then you would need to say we add them to content items. In my opinion, neither is correct.

We could say "add fields for taxonomy terms at the vocabulary level" and "add fields for content items at the content type level". But let's keep the language parallel for everything, one way or another.

We add fields to content types, and they show up when you add an item of that content type.
We add fields to taxonomy vocabularies, and they show up when you add a term to that vocabulary.

That's because 'field' is ambiguous : the data (on objects), or the field definition (attached to bundles, that's actually a field instance)

Point is : You can't say in the same sentence that comments and taxonomy *vocabs* can have fields. That's inconsistent and misleading.

The high-level user facing presentation of the feature should focus on objects : *objects* have fields - thus, comments, users, content, taxo *terms*.
That's how it's been advertised in the CHANGELOG, in the issue queue, in the various D7 blog posts : 'taxonomy terms can have fields'.
The fact that the collection of fields that are present in given object is assigned per bundle (content type, taxo vocab) comes second.

Point taken... Now how do we put this in mostly non-technical language so that the average Help user can understand it?

And let's make sure we are consistent about it, because fields are also not added to content types but to nodes. And by the way we are prohibited from using the word "node" in the Drupal UI and help (use content items or content, not "post" either). And the word Drupal is also prohibted by the way.

OK, here's a new patch. Hopefully I have addressed all the comments from #30 to #35...

NOTE: The help text is long and I screwed up the screen shot. The Reusing section and all below it is actually indented over to the left. Sorry about that... the text is at least OK.

Here's a better screen shot. I had to do it it two pieces and messed up the pasting on that other one.

I think it's good. Thumbs up. And by the way:

we are prohibited from using the word "node" in the Drupal UI and help (use content items or content, not "post" either). And the word Drupal is also prohibted by the way.

I didn't know this. Is it listed somewhere in the documentations standards?

The embedded documentation style guide still says to use "post" instead of "node", so that should be updated if this is now the correct way.

That guide is incorrect, sorry. I will file a doc issue about that.

In the meantime, this is the correct guide: http://drupal.org/node/501452 and its sub-page http://drupal.org/node/604342

Here's the doc issue: #706812: Two embedded doc/UI style guides...

So... can I mark this RTBC, or is that not a good idea?

chellman: I think we should wait for yched to also approve the patch, since yched had objections above.

I find the definition of machine name

the name stored in the database

to be incorrect. The label is stored in the database as well.
In order to not hold up this issue I uploaded a patch which changes that to

the name used internally

If that is considered a bad change just go with #36, no other changes.

Good change. :)

OK, I guess we have tstoeckler, jhodgdon, and chellman happy with this patch, so maybe that's enough consensus now?