Help File Fixup: forum

Thanks for doing this work, JuliaKM.

The help text has some capitalization issues. We only use caps for the first letter of the first work. So 'Locking Comments' should be 'Locking comments'. Should be a quick reroll.

Minor fix:
"while editing a forum topic will lock (prevent new comments) on the thread."
should be
"while editing a forum topic will lock (prevent new comments on) the thread."

I would also suggest moving the information on how to start a new forum thread into "Uses" rather than About.

Hmm... "The forum topic menu item (under Add new content on the Navigation menu) creates..."

We no longer have a Navigation menu, and this link may or may not exist in any given theme. Currently in Garland this is the management menu. "Add content" also appears in the default-enabled toolbar. Maybe it's best no to instruction how to add new content, and use the link provided.

Larger problem not sure if we can tackle it, but we can "help"

There are some seriously confusing things about the forum module... at the moment. As it is, you do most of the set-up at: admin/structure/forum on a page titled Forums... but in settings you're directed to manage content types, but are directed to a taxonomy term page (with the same title Forums) and you can add forum "topics" there as well. But if you add a topic there... you... later find out you actually added a forum.

The intro text has rightly been trimmed down, but I think we can do better. The relationship with these things can be more clearly spelled out if we 'break the mold' in the help page to suit this case. Demonstrating hierarchical relationships can be done with the use of lists. I know we chucked out the fruit. I'm open to other generic terms. This is an example:

• An optional Container, for example "Food", can hold:
• Forums, for example, "Fruit" which can hold:
• Forum topics, submitted by users, which start thread threaded discussions, for example, "Apple fan club"
• Comments, submitted by users, which reply to threaded discussions, for example, "I'd love to join!"

Otherwise it's hard to write out these relationships in text, but easier to demonstrate the hierarchy. Then we can explain how they can be put into containers, and you can have levels of containers and topics. (ok, my examples aren't that great... )

Example problems with forum module...

On admin/structure/forum/settings user is instructed "Select the content types to use in forums on the forum vocabulary page": which links to : admin/structure/taxonomy/2/edit
- on that page you expect content types, but you add "terms" then you later find out, oh I was adding forums...
And meanwhile the page title stays the same, and the tabs change... and you can only get back with our handy dandy back button. Made a screencast here:

http://screencast.com/t/YmM5NGJkZD

Latest screenshot from the patch:

At admin/help/forum:

(me neither found the syntax error in #7, which I take as the base, of course)

We no longer have a Navigation menu, and this link may or may not exist in any given theme. Currently in Garland this is the management menu. "Add content" also appears in the default-enabled toolbar. Maybe it's best no to instruction how to add new content, and use the link provided.

I think it's a good idea, so I refer to the drawer(toolbar) instead of the menú item.

There are some seriously confusing things about the forum module... at the moment. As it is, you do most of the set-up at: admin/structure/forum on a page titled Forums... but in settings you're directed to manage content types, but are directed to a taxonomy term page (with the same title Forums) and you can add forum "topics" there as well. But if you add a topic there... you... later find out you actually added a forum.

After the screencast and try it's clear: it's _really_ confusing(maybe I miss something, I'm only using forums for test).

IMHO it's better to refer just one place: admin/structure/forum, so there is no way from the help to go to the taxonomy administration, and instead go to the forum structure(maybe it would be a good idea to disable edit forum taxonomy by hand by default showing a message pointing to forum structure).

About the example, it makes sense, so I added it also(in plain html list instead of theme_list because of making it "simple", not sure)

There certainly is still a Navigation menu still in Drupal 7, so I would ignore that part of the comment above.

Anyway, regarding the latest patch...

a) What does this mean? "Add content in the drawer"? I have no idea what the "drawer" is.

b) There is a small indentation problem in the latest patch. All the lines should be indented the same in the code, and they should spaces and not tabs for indentation.

c) In the help section for admin/structure/forums, there needs to be more explanation, ending with a colon, before the UL. Such as
"The hierarchy is:"
Either that or drop the first sentence and make the outer UL into the introductory text. Something like this:
Forums have a hierarchy. The outer layer (which can be omitted) is forum containers, which can hold:
Anyway, it needs something... As it is, I thought it was pretty awkward.

Thanks for the review :-)

:-( I think I did not write enough explanation, so I'll try to fill the gaps.

There certainly is still a Navigation menu still in Drupal 7, so I would ignore that part of the comment above.

Yep, there's still a Navigation menu, the difference now is there is _not_ a Add content link in that menu, now it _is_ in the Management menu.

So, the idea here is not to refer anymore to the menus, and instead now refer to the default "toolbar"

Anyway, regarding the latest patch...

a) What does this mean? "Add content in the drawer"? I have no idea what the "drawer" is.

Yep, I was not sure to refer as that, but it seems like this is now the name for it, please see the snapshot when I pass the mouse over.

b) There is a small indentation problem in the latest patch. All the lines should be indented the same in the code, and they should spaces and not tabs for indentation.

Yep, you was right, one line was one space before the rest, so I fixed it. In the other hand, I could not find _any_ tbas in the patch :-(, so I do not understand.

c) In the help section for admin/structure/forums, there needs to be more explanation, ending with a colon, before the UL. Such as
"The hierarchy is:"
Either that or drop the first sentence and make the outer UL into the introductory text. Something like this:
Forums have a hierarchy. The outer layer (which can be omitted) is forum containers, which can hold:
Anyway, it needs something... As it is, I thought it was pretty awkward.

Ok, I follow the intro approach now.

One more thing I have no clear is: Is there a way to show "normal lists"(without list-style-type:none) in seven theme without hardcoding it?(I suppose there is a way, but I'm not sure how).

Any suggestions would be appreciated.

Here's a new patch - fixed some formatting, removed mention of "drawer", and put navigation in (this is consistent with other help text), and also majorly condensed the About section.

marvil07: re seven theme, it uses a reset CSS file that removes all styling, so at the moment that is how it looks (there are issues filed about this, so not to worry), and the styles definitely should not be hardcoded!

This is great except one minor typo:
" which start thread threaded discussions, "

I think the first word "thread" there needs to be removed?

Do that and I'm all for RTBC. :)

Oh, and this is really minor, I'd also remove an extra space between the = sign and the closing DL tag. Should only be one space there.

done!

The standard for capitalization is not being followed. See http://drupal.org/node/632280 -- should start with "The foo module" not "The Foo module" according to standard.

capitalization changed

WEBCHICK!!! that last patch has the bunk no caps - use the one from comment #15 please! http://drupal.org/files/issues/help_forum7.patch

Yeah, what arianek said... Standard for capitalization was changed, see http://drupal.org/node/537828#comment-2303764 and http://drupal.org/node/632280 -- we are now saying the name of the module should be capitalized. Sorry for the inconvenience but we need a new patch...

ack - please no more comments here (unless important) so webchick sees this note about the patch! she is keeping an eye out for this.

WEBCHICK!!! that last patch has the bunk no caps - use the one from comment #15 please! http://drupal.org/files/issues/help_forum7.patch

This is nice work! However, the UX team has been on a big push to remove big walls of text from admin/* pages (exempting admin/help*). So that hunk for 'admin/structure/forum' which explains what categories / forums are, while helpful, is not actually something we want to put on that page (unless you can get Bojhan/yoroy to approve).

If we're going to explain forums vs. forum containers vs. topics vs. whatever, IMO we should do so on the Forum module help page so that people who are confused can read it, but it won't take up 3/4 of the screen for everyone ever who has to manage forum outlines, regardless of their experience/comfort level. I would also prefer we use actual examples (perhaps from our very own forum) rather than non-sensical fruit-related ones.

However, I don't think any of that is worth holding up the rest of this patch. So I committed to HEAD everything in #15 except for that hunk. Bumping back to 'active' so we can further discuss if/how to integrate the additional explanation.

:-o part in HEAD, cool!

I just moved the example to the forum help page, replacing fruit with d.o real forums.

I cleaned this up a bit -- punctuation, wording, etc. Also moved some things around and added a section to Uses explaining how to create your hierarchy.

SORRY - wrong patch file here!!!!! See below

Sorry, I attached the wrong file. Try this one.

small code tweaks, made the first line match standard with the = ''; and then removed a trailing slash on one of the links. donezo.

+1

looks good and clean :-)

Looks great. Committed to HEAD!