GHOP #89: Improve documentation on arguments

Subscribing

Moving to the Views queue. Bound to be more Views-knowledgable people there than here. ;)

Claimed by kyl191.

kyl191's been posting his work here: http://drupal.org/node/206845

See discussion on http://code.google.com/p/google-highly-open-participation-drupal/issues/...

The two use cases listed so far at the handbook page in #4 look pretty good to me. If you can find 1 or 2 more use cases I think that would be great. If anyone reading this has any suggestions for interesting use cases that kyl191 could document, please follow up.

Ok. 2 more use cases of views added, now with nicer formatting! (Once again, it's available at http://drupal.org/node/206845)

This seems very good to me. A couple of things I noticed:

1) Some of the images are pretty big and have a lot of parts that distract the user from the essence of the image (see attached example)
2) It would be nice if the images were all hosted on Drupal.org I think the best way to do that would be to post them as attachments to this issue and then we can embed at least some of them into that page

I didn't test out or do a detailed review on each of the argument scenarios but all of them made sense in general.

I agree with greggles that these should be hosted on d.o.

@kyl191: If you aren't already, you should request to be a documentation maintainer on d.o by creating an issue in the documentation project and request to be a maintainer. That will allow you to set the input format of your handbook page to Documentation, which will allow you to use <img> tags in the text. You'll also be able to upload attachments (your images) to the handbook page.

@aclight: I'll post an issue after this (I assuming you're referring to posting here: http://drupal.org/project/issues/documentation). Once that's done, I'll redo the page as documentation and post the new link here.

@greggles: I realize that some of the images are big, but for the most part I'm trying to show the major differences when the arguments used are changed. For example, in the 'blog' view, I'm trying to show the difference between using an author's name and using the wildcard. If I crop the author's name one, I'm afraid that the user will think that there is more to the view that I'm not showing. By showing the entire screen, I'm showing the user that using this argument will give something like this, whereas using a different argument will give something totally different. Personally, I think that would make more sense to the person reading the page. (Essentially, the image is just to show an example of the output of the view, not to show any particular detail of views.)

I hope that clears up why I did the images in this manner.

If you have any questions though, please do post them, and I'll respond. Thanks!

My final goal was to get to a point where we could show the images in the body of the page. These are great images and by putting them behind a link, people will get less value from them.

Well, let's start with the assumption that 1280px wide is the most common width for visitors to Drupal.org - while 1024 is the most common on the internet in general, Drupal gets wider screens because we're fancy :) That said, 1024 is probably pretty common (we occasionally get bug reports about the drupal.org theme that are only visible if you have 1024 wide monitor.

So, next, the handbook has sidebars on both sides. With the browser at 1280 visitors only get about 690pixels in the middle. At1024 it's less than 600 pixels.

This page is already great. By cropping the photos (and perhaps re-shooting them using Minelli with your browser sized to 800 first) then we could embed them and really make this page over-the-top great.

I agree with greggles that it would be great if the images could be inline with the text. Maybe compromise would be to have a small cropped image inline that links to a larger image that is uncropped. You might be able to crop the images you've already taken for the inline images so you don't need to retake everything.

@aclight & greggles: I've cropped and uploaded the images to d.o, and redone the handbook page to use inline images. Hopefully it meets your expectations. :)

I just cropped the original images - Drupal doesn't like anything less than 825px (probably effectively 800px) across, and 825>590. So it was cropping and resizing.

(I've also uploaded all the original images along with smaller versions of those images if anyone wants to change certain images.)

Definitely - looks awesome to me.

I edited it to not "list" all of the attachments which I think makes the bottom of the page easier to handle.

I would have made the small images themselves link to a larger version, but that's more personal preference. This looks done to me. I'll mark it so on the google task tracker. Great job.

To get official credit, can you zip up everything you did and attach it to the issue in the google task tracker. Google is requiring students to upload everything there also. In addition, if you've done other tasks and haven't uploaded stuff, please go back and do so. If you made handbook pages, you can just copy into a .html file and put that and pictures there. Thanks.

Overall, I think this is very good work. There does appear to be a couple of issues:

1) don't use $arg at the end of a URL, it reduces performance and also makes summary views impossible. So blog/author/$arg should just be blog/author -- what follows will automatically be the argument.

2) Summary views weren't addressed here. I don't know that they had to be, but they're extremely handy and misunderstood. There's nothing wrong with them not being here but I was hoping to see one example of a summary view.

The page exists and I'm trying hard to clean the queue.

Thank you for this great documentation page, good job!