String freeze: Provide better content type descriptions

This one applies to latest HEAD changes.

Blog desc.:

- 'A blog is a regularly updated journal or diary made up of individual posts shown in reversed chronological order. Each member of the site may create and maintain a blog.'
+ 'A blog is a journal made up of individual entries, with new posts showing up at the top.'

Book desc.:

- "A book is a collaborative writing effort: users can collaborate writing the pages of the book, positioning the pages in the right order, and reviewing or modifying pages previously written. So when you have some information to share or when you read a page of the book and you didn't like it, or if you think a certain page could have been written better, you can do something about it.,
+ "A book is a collection of related articles in a hierarchical outline. For example, it can be used for creating manuals, handbooks and/or documentations, but can be used for virtually any purpose that requires a fixed structure."

Forum desc.:

- 'Create a new topic for discussion in the forums.'
+ '"Forum topics" are used to start a new thread in a discussion forum and can be categorized by selecting a forum or a forum container.'

Poll desc.:

- "A poll is a multiple-choice question which visitors can vote on."
+ "Poll can be used to collect opinion of visitors and users on a specfic multiple-choice question. Users can select their response and cast their vote on the poll."

Page desc.:

- 'If you want to add a static page, like a contact page or an about page, use a page.'
+ 'To create static pages with infrequently changing content, a \"page\" is used. This content type is highly generic and can be used for about any purpose.'

Story desc.:

- 'Stories are articles in their simplest form: they have a title, a teaser and a body, but can be extended by other modules. The teaser is part of the body too. Stories may be used as a personal blog or for news articles.'
+ 'Stories are simple articles used to provide the actual content of your site. This content type is highly generic and can be used for about any purpose.'

This is how the changes apply against current HEAD version (For anyone who may contribute this way). Patch is attached.

Ok, I've updated this patch to apply again and after a long discussion on IRC come up with some new descriptions. Here are the page and story text since its a little harder to gleam from the patch. Great work guys, this looks a lot better.

A page is a tradition web page commonly used for relatively static content like an "about us" page. This content type is very generic and can be used for about any purpose.

Stories are simple articles that allow separate teaser and body sections. This content type is very generic and can be used for about any purpose.

Nice! The language is much more descriptive. +1

typo in the text for page: "A page is a tradition web page" should be "A page is a traditional web page"

However, I don't like this use of "traditional", since it's not actually static- rather something like:
"A page is commonly used for relatively static content like an "about us" page. This content type is very generic and can be used for about any purpose."

Also, I think the text for story needs work- it makes it sounds like the teaser is entered separately, when it simply uses the same mechanism as all other content.

Should we be consistent with singular/multiple ("Blog entries...A page..."). Also, I think we shouldn't end a sentence with a preposition (that's what "of" is right?). Wasn't there talks of removing story from core? It seems kinda silly now that we're writing directions. "A story is exactly like a page, except it's called a story." We should explain what the use is of having two identical types in there. For me, it's using Views to easily split them up, but for a noob, what's the benefit?

"and can be used for about any purpose."

This does not sound right. I would say:

"and can be used for just about any purpose."

simpler like this:

Story: Stories are simple posts and hold content from your site. This content type is generic; there is no difference in behavior to a page.


I call this a bug report so that it shows up among critical issues (/me is too lazy to change the critical issues link).

I like these *much* better than the current descriptions. I agree about the need for consistency between singular and plural. I vote to make them all singluar, since you see the description when you are ready to create a single node and the content type names themselves are singular.

For page/story, I think that

Page: A page usually holds static content that doesn’t change very often. There is no difference in behavior to a story. This content type is generic, and can be used for about any purpose.

Story: Stories are simple posts and hold content from your site. There is no difference in behavior to a page. This content type is generic and can be used for about any purpose.

is confusing since you describe them differently, then say they are the same (it looks like you can't put static content in a story, only a page, for instance). I would describe them the same way, and then say that they can be used as alternatives when you need to have two different content types in order to be able to group them differently, assign them to different categories, or give them different access options.

So here's a possible description:

Page - A page is a generic content type that can be used for just about any purpose. A page behaves similarly to a story, and can be used as an alternative to a story when you need to have two different content types in order to be able to group them differently, assign them to different categories, or give them different access options.

Story - A story is a generic content type that can be used for just about any purpose. A story behaves similarly to a page, and can be used as an alternative to a page when you need to have two different content types in order to be able to group them differently, assign them to different categories, or give them different access options.

I like KarenS' later descriptions or story and page. My one comment would be that they are somewhat long.

I agree they are kind of long and I've been trying to think of a way to make them more compact. How about:

Page - A page is a generic content type that can be used for just about any purpose. A page behaves similarly to a story, and can be used as an alternative to a story when you need a way to provide different categories or access options.

Story - A story is a generic content type that can be used for just about any purpose. A story behaves similarly to a page, and can be used as an alternative to a page when you need a way to provide different categories or access options.

Actually, as I think about this more, I wonder if it's a good idea for them to refer to each other. What if one or the other is deleted? Then the description looks odd. How about this instead:

Page - A page is a generic content type that can be used for just about any purpose. A page behaves similarly to other generic content types, and can be used as an alternative when you need a way to provide different categories or access options.

Story - A story is a generic content type that can be used for just about any purpose. A story behaves similarly to other generic content types, and can be used as an alternative when you need a way to provide different categories or access options.

Actually.....

I'm going to have to -1 KarenS's descriptions (sorry!)

Simply because these descriptions are for _users_ who will be creating these content types from node/add/. They're not for _admins_ who will be configuring a site.

I think KarenS's descriptions work, they just should probably be moved to the admin/help/page|story links, or else to help text at the top of the admin/node/types page (that actually might be best -- a generic description of what types are and how they work). Those are places purely for administrators who are trying to configure a site, rather than descriptions that all users see.

For page/story I'd lean toward stuff more like:

"Pages are for static content such as an about page"

and

"Stories are for things like news articles and such"

Obviously, these are just "starter" descriptions and can be edited to whatever is necessary, so they don't need to be overly complex.

I simply agree with webchick; maybe this can settle it?

For the record I don't understand why the 'story' content type still exists as a default in core, I find it to be redundant. That said here is my attempt:

"Pages are the simplest type of content. They can be used as a way to create a 'static' page within your site, such as an 'about us' page."

"Stories can be used to create basic news articles for your site. By associating a vocabulary with them you can classify your articles."

What color is that bike shed anyway? ;) FWIW i agree with wbechicks sentiment but not her language choice.

I'm going to lower the priority of this bug. It doesn't break anything. Hope you understand.

We're post-string freeze; this will have to wait until 6.x.

No.. we don't want any admin instructions on the create content page. This is user-facing text, and is what all end users on the site will end up seeing when they go to create blog posts and such. Words like "content types" and "workflow settings" and such should be restricted to admin pages.

Someone asked : For the record I don't understand why the 'story' content type still exists as a default in core.

The answer is given By Karen above :

A story can be used as an alternative to a page when you need to have two different content types in order to be able to group them differently, assign them to different categories, or give them different access options.

However, although this was very true for 4.7.4., it is less true with drupal 5 as we are able to create content types in core.

I very much like pwolanin's description for pages -- and I think the word "traditional" is definately out of place no matter how you put it :

"A page is commonly used for relatively static content like an "about us" page. This content type is very generic and can be used for about any purpose."

Best I can do to make these descriptions parallel, and of a form that I'm likely to easily remember when I go to enter new descriptions for new content types.

We badly need a new set of content type descriptions; I'm not advertising the attached patch as a panacea for all that ails these descriptions, but it is a start.

Applies to HEAD.

Moving to CNR to solicit reviews.

Thanks for looking through the patch.

Unless I'm just not seeing an instance of missing a tag -- which is certainly possible, I have all the right places wrapped in em in the text.

On retrospect, it might be non-obvious, but my intention was to wrap the first instance of the actual content type name (or as close as possible to the first) in em, in some cases, like the entries for "Blog entry" and "Book page", the description deals with the larger issues of Blogs and Books first. Blogs and Books aren't wrapped, but "blog entries" and "book pages" are, though they occur later on in the sentence.

I'm going to leave this CNR to see if I can come up with a way to make the descriptions for "Blog entry" and "Book page", at least, more 'standard'.

Again, I want to ask everyone in this thread to remember that this is user-facing text. That means it should describe _only_ what the difference is between a page and a blog entry or whatever from a content creator's perspective, and not mention any of the crazy admin/settings/theming kind of stuff you can or might do. We can open a separate issue for "Make the admin/content/types screen (or admin/help/node) have a better help description of the kinds of stuff you can do with different content types."

That said, here's a review of keith.smith's descriptions.

All around, I'd give a +1 to the <em>type</em> convention. Makes it clear that you're defining something.

And also the biggest +1 ever to the large number of inconsistencies that were fixed in this patch. All descriptions now follow a consistent "A [something] is..." format.

-      'description' => t('A blog is a regularly updated journal or diary made up of individual posts shown in reversed chronological order. Each member of the site may create and maintain a blog.'),
+      'description' => t('A blog is an online journal or diary made up of individual <em>blog entries</em>, often displayed in reversed chronological order.'),

Let's ditch "often displayed in reversed chronological order" -- not only is that not something most people would say in normal conversation, ;) but it's also alluding to the fact that things _may_ be displayed a certain way or not. It either is or it isn't on the particular site they're using. So let's remove the ambiguity.

-      'description' => t("A book is a collaborative writing effort: users can collaborate writing the pages of the book, positioning the pages in the right order, and reviewing or modifying pages previously written. So when you have some information to share or when you read a page of the book and you didn't like it, or if you think a certain page could have been written better, you can do something about it."),
+      'description' => t("A book is a structured collection of <em>book pages</em>, each individually created and arranged in the proper order within the book. Begin a new book by creating its initial book page."),

This is a huge improvement, imo. But there are a couple problems:
a) As much as I love the addition of answering the question, "how the heck do I create a book anyway?" only people with "create new books" permissions can do this, so it will be confusing to see that in the type description and not actually have the option. So maybe instead add this (if it isn't already) to the help text on node/add/book so it can dynamically check what permissions you have and give you proper instructions (separate patch/issue).
b) "each individually created and arranged in the proper order within the book" is a bit awkward. I don't really have any suggestions off-hand, but maybe we should split that into two sentences or something? "You can create and re-order pages..."

-      'description' => t('Create a new topic for discussion in the forums.'),
+      'description' => t('A <em>forum topic</em> creates a new conversation or discussion topic inside a user-specified forum.'),

a) Let's ditch "user-specified"
b) I'm left wondering what's the difference between a new conversation and a discussion topic. Is simply new "thread" too technical, I wonder..?

-      'description' => t("A poll is a multiple-choice question which visitors can vote on."),
+      'description' => t("A <em>poll</em> collects the opinions of visitors on a user-specified question, and maintains a simple running count of responses."),

Again, let's get rid of the text "user-specified"
Other than that, I think this one is okay? Other opinions?

-      'description' => st('If you want to add a static page, like a contact page or an about page, use a page.'),
+      'description' => st('A <em>page</em> provides a title and content area, and is ideal for pages containing infrequently edited information. Examples include common <em>About Us</em> or <em>For More Information</em> pages.'),

"infrequently edited" sounds a bit awkward, but I'm not sure what else to change it to.
I LOVE the inclusion of the examples. :)

-      'description' => st('Stories are articles in their simplest form: they have a title, a teaser and a body, but can be extended by other modules. The teaser is part of the body too. Stories may be used as a personal blog or for news articles.'),
+      'description' => st('A <em>story</em> provides a title and content area, and can be used to logically separate a certain type of content from other entries. Press releases, for example, may be created as stories so that their content can be differentiated from pages, book pages or blog entries.'),

K, this one I have a problem with...

"can be used to logically separate a certain type of content from other entries." No... That's what it means for an administrator, and that's true of all content types, not just stories. You need to answer the question, "What is a story from a user's perspective?" The whole second sentence suffers from this problem as well.

We need something a little more like, "A story can be used for short posts, such as a News section," but better. ;P

Oh, one other thing I thought of as I was waiting for the page to refresh (slow load times are dangerous for that ;)):

Examples include common <em>About Us</em> or <em>For More Information</em> pages.'),

Would it still be proper English to include those in "quotes" as opposed to emphasis? Simply because you use the emphasis earlier to indicate a definition, and these are merely examples.

Thanks webchick! Those comments were extremely helpful.

I tried my best to address your comments in the attached patch. Note that I did change some of the descriptions that you identified as "ok", in the interest of greater uniformity. Book and blog posts are reworded, as well.

I did mention default workflow states on pages and stories, because, frankly, without doing that, it is hard to describe why there IS a story type in any cogent manner.

Please re-review...

This patch would remove the hard-coded book type from the book module: http://drupal.org/node/146425

As it stands, those doing a D5->D6 update with existing 'book' type content would get a 'book' type created with the description:

"A static page. These posts (or any other type) may be added to a book outline to create a hierarchical structure for your site."

Good work. We're getting there...

On all, remove "provides a title and content area" ... it can provide more than that, so just "A blog entry is used to create individual entries..." and "A book page is the building block of.."

-      'description' => t('A blog is a regularly updated journal or diary made up of individual posts shown in reversed chronological order. Each member of the site may create and maintain a blog.'),
+      'description' => t('A <em>blog entry</em> provides a title and content area, and is commonly used to create individual entries in an online journal, or <em>blog</em>.'),

and is commonly used => is used. let's remove ambiguity.

-      'description' => t("A book is a collaborative writing effort: users can collaborate writing the pages of the book, positioning the pages in the right order, and reviewing or modifying pages previously written. So when you have some information to share or when you read a page of the book and you didn't like it, or if you think a certain page could have been written better, you can do something about it."),
+      'description' => t("A <em>book page</em> provides a title and content area, and is the basic building block for creating <em>books</em>, one mechanism for managing and displaying structured content."),

Hmmm. Don't like the definition for books. Let's talk about what a book is: it's a structured group of pages with previous/next links.

-      'description' => t('Create a new topic for discussion in the forums.'),
+      'description' => t('A <em>forum topic</em> creates a new discussion thread inside a forum.'),

Works for me.

-      'description' => t("A poll is a multiple-choice question which visitors can vote on."),
+      'description' => t("A <em>poll</em> presents a single text-based question and a list of pre-defined responses, and maintains a simple running count of responses."),

This went and got complicated again. :( I liked your previous definition much better, as it didn't have things like "text-based question" and "pre-defined responses" ... people know what a poll is.

-      'description' => st('If you want to add a static page, like a contact page or an about page, use a page.'),
+      'description' => st('A <em>page</em> provides a title and content area, and is an ideal choice for displaying information that seldom changes. An "About Us" or "For More Information" section, for example, are often created as page entries. By default, visitors may not comment on pages, and the page posts are not automatically promoted to the front page.'),

I'd remove "By default, visitors may not comment on pages, and the page posts are not automatically promoted to the front page." This was probably my fault... we talked about this on IRC. I just meant it as background information, not that it should actually make it to the user-facing text.

Otherwise, this one looks good (with removal of "title and content area" mentioned at the top).

-      'description' => st('Stories are articles in their simplest form: they have a title, a teaser and a body, but can be extended by other modules. The teaser is part of the body too. Stories may be used as a personal blog or for news articles.'),
+      'description' => st('A <em>story</em> provides a title and content area, and is often used to tailor a workflow pattern to the needs of specific types of content. Press releases and news articles, for example, are often created as story entries. By default, visitors may comment on story entries, and story posts are automatically promoted to the front page.'),

Noooo.. :) "tailor a workflow pattern to the needs of specific types of content." ... an end-user is never going to do this. This is something the administrator might do, but creating a simple story doesn't tailor any kind of anything. It's just a story.

How about something like:

A <em>story</em> is a simple post that other visitors may comment on. A "news articles" or "announcements" section, for example, can be created with story content.

(and yes, it's true that commenting may be turned off, but in that case the administrator can update the description here.)

I didn't mention press releases because in all likelihood you probably use 'story' for that, since you don't want people commenting on your press releases. ;)

kkaefer: It is indeed hard, and at the end of the day, may not match what is configured on sites that adjust the defaults. But, that said, almost any of the descriptions in this issue are equal to or better than those we currently have.

My big goal is consistency, simply because items in lists that aren't reasonably parallel give me hives.

These are difficult to word, not only for the reasons that kkaefer notes, but also because many of them are two-word content types, which royally mucks around with subject/verb agreement, etc. Presenting descriptions that are [mostly] in active voice, consistent, parallel, and reasonably helpful but not overly technical is a surprising challenge.

webchick, kkaefer: All that said, here's another iteration, using much of the feedback from #drupal.

- A blog is a regularly updated journal or diary made up of individual posts shown in reversed chronological order. Each member of the site may create and maintain a blog.
+ A <em>blog entry</em> is a single post to an online journal, or <em>blog</em>.

- A book is a collaborative writing effort: users can collaborate writing the pages of the book, positioning the pages in the right order, and reviewing or modifying pages previously written. So when you have some information to share or when you read a page of the book and you didn't like it, or if you think a certain page could have been written better, you can do something about it.
+ A <em>book page</em> is a page of content, organized into a collection of similar entries known as a <em>book</em>. Book pages are automatically part of a simple navigation system, displaying automatic links that lead both forward and backward to adjacent pages within the book.

- Create a new topic for discussion in the forums.
+ A <em>forum topic</em> is the initial post to a new discussion thread within a forum.

- A poll is a multiple-choice question which visitors can vote on.
+ A <em>poll</em> is a question with a set of possible responses. Polls automatically provide a simple running count of the number of times each response is selected.

- If you want to add a static page, like a contact page or an about page, use a page.
+ A <em>page</em> is a simple and ideal choice for displaying information that seldom changes. An "About Us" or "For More Information" section, for example, can be created as a page.

- Stories are articles in their simplest form: they have a title, a teaser and a body, but can be extended by other modules. The teaser is part of the body too. Stories may be used as a personal blog or for news articles.
+ A <em>story</em> is content that, by default, allows visitor comments and is automatically listed on the site's front page. A press release or announcement, for example, can be created as a story.

Note: while pasting in the above I noticed that there are a few (or at least one) " terminators that should be '. I'll correct this code style issue in the next iteration.

Oh...and obviously, when the book patch hits, this may get more complex since not only book pages may participate in a book's organizational fu.

...and forgot to change status...

- A book is a collaborative writing effort: users can collaborate writing the pages of the book, positioning the pages in the right order, and reviewing or modifying pages previously written. So when you have some information to share or when you read a page of the book and you didn't like it, or if you think a certain page could have been written better, you can do something about it.
+ A <em>book page</em> is a page of content, organized into a collection of similar entries known as a <em>book</em>. Book pages are automatically part of a simple navigation system, displaying automatic links that lead both forward and backward to adjacent pages within the book.

has a too many automatically and automatics in it; how about nixing the first one such that:

- A book is a collaborative writing effort: users can collaborate writing the pages of the book, positioning the pages in the right order, and reviewing or modifying pages previously written. So when you have some information to share or when you read a page of the book and you didn't like it, or if you think a certain page could have been written better, you can do something about it.
+ A <em>book page</em> is a page of content, organized into a collection of similar entries known as a <em>book</em>. Book pages are part of a simple navigation system, displaying automatic links that lead both forward and backward to adjacent pages.

Also, removed the last couple of words from that description; I *guess* its obvious that adjacent pages to a book page are likely also within the book.

Reflected that last description change in #43 in this new patch.

Rerolling to remove minor fuzz, and *bump*

Rerolled as well as made some text changes [again] from my last patch. I know this is seriously minor stuff in the face of an impending beta release, but the 'Create content' page is important. That page is an important part of how many many people interact with a Drupal site.

I certainly won't suggest these alterations are perfect, but I believe they are substantial improvements over the existing text, if only because the content descriptions are much more parallel with one another. I'll happily roll a patch for any other alternatives put forward, however, in the hopes of improvement here.

Assigning to shiny new documentation component. Woohoo.

I'll also try to give this a review later too. :)

*bump*

Anybody interested in quick review? 'Sure would be nice to get some better descriptions on the Create content page; if not the ones in this patch, than perhaps some of the good suggestions from other patches in the issue?

Reading through.
Poll I'd change the last sentence to:

A poll, once created, will automatically provide a simple running count of the number of votes.

I think most people think about voting on polls, not selecting responses.

Page second sentence:

By default, a page entry does not allow visitor comments and is not featured on the site's default home page.

(because they can change the default when they post it or in the content type settings).

Everything else looks good to me and a big improvement.

I modified the suggestion for poll so that it now says:

A <em>poll</em> is a question with a set of possible responses. A <em>poll</em>, once created, automatically provides a simple running count of the number of votes received for each response.

If I end that second sentence with just "number of votes received", it is not clear how the second sentence relates to the first. However, the first sentence sounds clunky with "a question with a set of possible votes." So perhaps this will work and address the concern in #49.

In the page and story definitions, I added a "By default, " clause at the beginning of the last sentence, and changed the "default" home page to "initial' home page to avoid overusing words.

When initially working on this patch, I really struggled with this default configuration business, because realistically, the settings on someone's site may not follow these guidelines at all after one "adjusts" the content type settings. Though I think this change was a good one, and will work for 95% of the cases, these descriptions are user-configurable after installation -- I think the only real way to do this is have the descriptions match the settings as they are installed out of the box, and then an admin must remember to adjust her content type descriptions at the same time that she adjusts the settings, in order to keep the descriptions accurate.

That said, I almost have never changed these descriptions in practice, regardless of how I've mangled the comment and workflow settings.

A new patch is attached, so setting back to CNR.

Patch applies fine, new text is much better. Should be ready.

I've committed this to CVS HEAD. Thanks.

This introduced a double quoted string with unescaped double quotes, breaking installation.

Well crap. I'm not sure how I missed that, but its' totally my fault.

I should have RTBC'd the patch in my earlier post. I don't suppose it matters in this case whether the double quotes are escaped or the quote (apostrophe) is escaped (since there are both inside a the double-quoted string).

This patch is not correct. Don't use \" if you have a chance to put single quotes around the complete string.

This one would be correct:
<?php
'description' => st('A page, similar in form to a story, is a simple method for creating and displaying information that rarely changes, such as an "About us" section of a website. By default, a page entry does not allow visitor comments and is not featured on the site's initial home page.'),
php>

Additional you should use single quotes whenever possible (for e.g. no \n inside)... the prior patch have introduced some double quotes, where it is not required. This should be changed to surrounding single quotes, too.

Hass - please notice that there's a single quote in the string too. Near the end, site's.

We need to fix this quickly.

Oopsie. Committed to CVS HEAD. Thanks for the quick patch.