Help TODO: Create a page to list recent stories

I've followed the instructions in that '.doc' and succeeded in making that block. The facts are ok (and see comments below).

I can't vouch for type correctness: I don't have Word and my viewer shows me plain text.

I certainly think such "step-by-step"s are needed, especially ones demonstrating the "non trivial", or "innovative", stuff: relationships, default arguments, grouping, overriding options from 'Default', etc. If not shipped with the official help, they can be made pages in the handbook.

Having said that, I pity those who need to read a step-by-step recipe. The only way to follow those myopic steps --"click this, type that, breath in, breath out"-- without losing your sanity is to turn your brain off.

[...] and I'll convert it into HTML for use.

Not by Word's "save as html", I hope.

Comments:
- "Drag the four-sided arrow...", one also needs to click 'update' to save the new field order.
- "Next to the 'Items to Display' select 10", need be "click 10".
- In my browser it's not "click ctrl" that I need to do to open a page in a new tab/window.

moofie: Thanks for the review!

mroswell: Would definitely prefer a html or even a simple text file to a word doc. .doc files can be a bit of a pain to manipulate in terms of turning to HTML. Thanks for this effort though, these little tutorial things are useful.

One thing that webchick mentioned when she was doing some proofreading is that the existing tutorial doesn't explain why we're doing this, so one thing that will help also is a paragraph to explain what this tutorial will demonstrate.

Changing title to be more descriptive

Attached is the text, converted to HTML, with Moofie's recommendations incorporated.

This brings up an issue: I recommend that "the PHP docs" link be set to open in a new window (target="_blank"). Otherwise users may lose some settings when they go back. If that change is made, modify the attached text, accordingly.

BTW, here's a nice Word-to-HTML cleaner. http://www.algotech.dk/word-html-cleaner-input.htm

(I'm modifying it a bit to conform to webchick's standards, just a sec.)

This brings up an issue: I recommend that "the PHP docs" link be set to open in a new window (target="_blank").

I've started a new issue for this, #284900: Open 'php.net/date' in a new window.

Here's a type-corrected version. I also removed the hard wraps.

(The 'open in new page' instructions I turned into an HTML comment which can be restored, or deleted altogether, depending on how the other issue is settled.)

(Off topic: Marjorie, how did you manage to attach a '.html' file? D.O. tells me this extension isn't allowed. Never mind, I guess you have some special editor permission.)

Here it is.

One thing that webchick mentioned when she was doing some proofreading is that the existing tutorial doesn't explain why we're doing this, so one thing that will help also is a paragraph to explain what this tutorial will demonstrate.

Merlin,

Were you planning to _embed_ this 'recent stories' howto in the 'getting started' page?

Or do you want to make it a child page, and also turn the 'list users' howto into a child page?

Child pages (presumably just regular links in Advanced Help?) sound like a good idea.

example-recent-stories is a much better name. Thanks.

If this helpful patch gets included, the commented-out part can be removed.
http://drupal.org/node/284900

mooffie: I was initially planning to just make it part of the getting started page, but I have no problems with sections growing large enough to simply become their own entity.

I'm just familiarizing myself with Views2, and this step-by-step was handy. Thank you for it! In case it helps, I just made some changes, which you may or may not find useful.

First off, I thought the list was long, and daunting. Going back and forth, it's hard to find exactly where I was. I divided out the list into tasks; explaining what each task was, therefore hopefully reinforcing some of the concepts to the new user. This also lessened the apparent list of "steps" to 8. This makes the HTML more complex, but it reads better on the screen.

I think there are some non-intuitive things that should be explained more explicitly on this occasion (someone's supposed first view, and/or their first time seeing this interface). As in... I seriously didn't see the options magically appearing below for an embarrassingly long time. Not sure if anyone is quite as thick as I am, but just in case I think a general introduction to *how* the interface works would help. I added that.

I also saw some missing mentions of "Click Update" in the beginning, whereas it reappeared in later steps... And then referred to the drop-down menu usage. And... some other things for consistency or clarity... and I think that's about it.

An awesome improvement. Thanks.

hmm, I have been editing also and working through the examples - here's a patch which makes 2 separate child files. Please compare to #12 to see if I missed anything.

I like Heather's improvements. We should treat our users as humans, not as robots.

So I'm attaching Heather's version, with some refinements and fixes. (1. I'm using {h3} for headers (instead of {strong}, that has its own use in this howto); 2. changed headers to be nouns; 3. Fixed a few words.)

Pwolanin, I also incrorporated most of your new "Block configuration" into this (this is about the only change I located in your version).

The only downside is that now the existing 'List Users by Role' howto has a different style (the "robot" style). I suggest we leave fixing that other howto to a different issue; I'm exhausted already.

What's left is to repeat the process pwolanin did in #14 but to use this new file instead. Pwolanin, could you please do that? Or I could do that myself, if somebody approved this new version.

yeah i saw that "list users by role" help file. i'll take a stab at it today, and post it up for your review.

I made a few other minor changes like <strong> tags for the + icon, and ↑↓ for up/down.

Patch works. Looks fine to me.

(The only problem, which I mentioned, is that the first howto, 'list users by role', isn't as friendly as this one. But this can be tackled in a different issue.)

@moofie: i made one yesterday, to fix the 'list users by role' .. i should have added the link here (since i put it in a new issue, as you recommended)

http://drupal.org/node/285275

I ran through this howto and everything works perfectly. It is very easy to understand, even for a views newbie.

As this is a very simple view (much simpler than the users by role view), I suggest this is the first example on the Getting started help page, not the second as it is currently.

I agree, absolutely.

Here's a re-roll of the patch. Changes:

- Added <P> tags in two or three places so that Drupal's filter doesn't generate invalid HTML.

- Restored the little sentence talking about those 'F j, Y' date codes.

- Changed the "A first look at the interface" header to "About the interface", because this HowTo may not be the first one.

Alternatively, here's a "mega patch". It's the same as above but it also merges in that other "users by roles" updated HowTo.

I suggest this is the first example on the Getting started help page, not the second as it is currently.

(Switching the order of the two HowTo's, that's a trivial matter, so it shouldn't hinder accepting this patch (or the non-mega one) as-is.)

Very minor point, but...

The first line of text in each file begins with 'In this example...'. But that line is not enclosed in <p> tags in either file. To be consistent, this should be changed.

ff1: These help texts run through Drupal's filters which add the <p> tags, so it isn't necessary to explicitly type them.

moofie: Sorry. I saw your comment in #23 and thought that these ones may have been missed. Thanks for letting me know. :)

I will look at committing this when I return from vacation. With the two of you working back and forth, I think we're getting very good results, and I am very happy with what you're doing. Thanks for the efforts. I'll be back on Sunday and probably will look at this around Monday, so if you have further improvements over the weekend, keep at them! If not, then it'll be an easy commit.

This is really, really great work. I appreciate this a great deal. Thank you very much for the effort! Efforts like this will take my mediocre, quickly written documentation and turn it into something actually good.

Merlin, `example-users-by-role.html` doesn't show up in the CVS.

Perhaps you needed to do 'cvs add ...' ?

If you lost that file, don't bother with a rollback:

I'm attaching the file here, in case it makes your life easier. It's exactly the same as in the patch. Nothing's changed. Just put it in the 'help' folder and do 'cvs add'.

(Everything else in your commit is fine, I checked it.)

Man. And I did cvs add; I must've somehow did the command to only get one of the example files. Weird. Thanks!

What a fine teamwork! :-)

Thank you Heather, and Marjorie, and Peter, and Ian, and... Merlin!!

Terrific teamwork indeed. Each edit improving the last. And to add to the thank-you list: Thanks, also to Moofie. Todah, Tov M'od. Yofi. (A bit of transliterated Hebrew, there... "Thanks, very good, cool," if i"m translating accurately.)

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