048 - Create a Joomla! QuickStart Guide

Google's Highly Open Participation Program tries to get young students into Open Source and Joomla! specifically. Everyone is welcome, there are not limits. You can be a coder, documenter, tester, translator to help out. Jump in and start helping!
User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Sun Dec 16, 2007 8:37 pm

Alright, on to issue 48!

Quoting the Original GHOP Issue,
Write a QuickStart Guide to help end users get onboard fast with Joomla!.
Include screen shots and easy to follow instructions that demonstrate the
following:
This one should be fun! Is using openoffice a requirement? I don't mind, but I'm curious.

Also, for the XAMPP instructions, would you like me to write my own or use stuff from the XAMPP website? Also, should I do primarily windows only, or search out a mac and linux box and do it there too?

Google Task

Task claimed: Dec 16 Due: Jan 6

(Did I get the title right this time? ;) )
Last edited by AmyStephen on Tue Jan 08, 2008 2:38 am, edited 1 time in total.

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Wed Dec 19, 2007 12:01 am

*Bump for mentor assistance*

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Wed Dec 19, 2007 2:03 am

Sorry Kevin!

First of all, I'm glad you got this task. It has great potential to be "the document" that most people grab when they build a website. Most people will read the guide - if it's 10 pages (or 20 pages) or less.

You can re-use XAMPP text - but I wouldn't get into too many details. Show the very basics - even say - follow the prompts. Show them where to download it - how to start the process - and let the install take over.

Then, when it's time to install Joomla!, tell them how to create a new website folder and database using phpMyAdmin - then fire off the J! install.

Then, I'd like to see it cover some of what's in this guide, but simpler.

Yes, Kevin, we'd like to see you use Open Office, if at all possible. It's open source, we're open source. Peanut butter and Jelly, right? ;) If you have a reason you can't - that's cool - but we'd like to do that, if possible.

Thanks for everything you are doing for the Joomla! community - you absolutely rock!  8)
Amy

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Sat Dec 22, 2007 2:53 am

Alright, now that finals are over at school, I'm putting more effort into this.

One question - the thick install manual states "Caution: Please completely read through the Installation Manual before commencing the installation, it may well save you a lot of grief!"

I don't know if it's just me, but it seems like making a quick start kind of makes one of the two documents not so useful - especially since this document will be a very skimmed down version of that one... just an observation.

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Sat Dec 22, 2007 4:02 am

Kevin -

After years of living, I have come to the realization there are two types of learners in this world (roughly.)

There are those, like my husband, who actually read the instructions that they say you should read before beginning a project. People like that will use the thick Install Guide and tend to sail through life uneventfully, anticipating problems before they appear, responding appropriately to all prompts, never needing backups.

Then, there are those of us who do not like long guides and have decided it is easier to simply do it, and pay for the consequences later, than read a long guide. We attend the College of Hard Knocks where portions of guides are read only in emergency mode as fires rage out of control.

Having harmed ourselves more often than we care to admit, we have adaptly, slightly, to actually read a Quick Start Guide.

Please make us one. Get right to the point. Don't tell us too much. And, for crying out loud - don't tell us about every single parameter! But, try to give those of us with ADHD the very high points - as quickly as possible - then, get out of our way!

Amy  ;)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Sat Dec 22, 2007 4:10 am

Hah... i'll make this an anti-nerd document...  :D

Thanks again Amy!

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Sat Dec 22, 2007 8:11 pm

Here's an interesting one for ya... I'm using Windows Vista, which didn't come with EITHER of the default Joomla fonts installed! Any chance I could get a copy of New Baskerville and Helvetica from someone?

Also, I'm having issues with colors too. I'd LOVE to use the colors defined in the Joomla! Brand Manual, but I cannot get certain colors to work in OpenOffice. No matter what I do, the green won't show up correctly with the given values for RGB or CYMK.
Last edited by Kevin8020 on Sat Dec 22, 2007 8:18 pm, edited 1 time in total.

User avatar
trombonechamp
Joomla! Explorer
Joomla! Explorer
Posts: 403
Joined: Thu Nov 29, 2007 9:37 pm
Location: Minnesota, USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by trombonechamp » Sun Dec 23, 2007 2:05 am

Both Halvetica and New Baskerville are copyright Adobe.

Arial is almost identical to Halvetica.
For New Baskerville, I have seen other people using Times New Roman or Georgia.

I hardly know anything about colors.  Sorry!  :(
Leonard Bernstein for President -
Web Development Services: www.BernsteinForPresident.com
My Software Freedom Blog: Trombonechamp.Wordpress.com

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Sun Dec 23, 2007 3:46 am

Agree with Max. I don't any of us - contestants included - have access to those Fonts.

Don't worry about it.

Amy :)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Thu Dec 27, 2007 9:18 pm

Here is my progress so far. I've got a long way to go, but I've finished the installation section as well as the content addition section. Do you think I should try to be more detailed, or am I too detailed?

Thought anyone?

http://www.kahstudios.com/kevin8020/joo ... kstart.odt (NOTE: File is 1.35MB)

Thanks!
Last edited by Kevin8020 on Thu Dec 27, 2007 10:38 pm, edited 1 time in total.

User avatar
trombonechamp
Joomla! Explorer
Joomla! Explorer
Posts: 403
Joined: Thu Nov 29, 2007 9:37 pm
Location: Minnesota, USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by trombonechamp » Thu Dec 27, 2007 9:40 pm

-What if the end user is using Mac/Linux?  If you choose not to include support for these platforms, you should at least rename it "QuickStart Guide for Windows Users"
-You forgot the "!" in a few places. (esp in the screenshots you took, the site is named "Joomla 1.5" without the "!"!)
-It may be helpful to hyperlink the things in the table of contents to the location in the document.
This is a good start!
Leonard Bernstein for President -
Web Development Services: www.BernsteinForPresident.com
My Software Freedom Blog: Trombonechamp.Wordpress.com

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Thu Dec 27, 2007 10:26 pm

-Good thought on the Mac/Linux thing. For the time being, I'll rebrand this as "for windows" and will probably do a Linux and Mac guide too... not that hard.
-Good catch! I've been having a hard time remembering the "!" - not easy... I'll go get those fixed.
-And yep, TOC hyperlinks are on my list :)

Thx!

EDIT: Updated file: http://www.kahstudios.com/kevin8020/joo ... kstart.odt (NOTE: File is 1.35MB)
Last edited by Kevin8020 on Thu Dec 27, 2007 10:38 pm, edited 1 time in total.

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Thu Dec 27, 2007 10:41 pm

Exact right amount of detail, IMO.

I think it's fine to start the guide out by saying this is done using a Windows setup. There is little difference in the things you are showing between Windows, a Mac and a Linux client.

Really good work, thanks!
Amy :)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Sat Dec 29, 2007 12:26 am

Alright, I've completed the first draft. I've got a bunch of review to do though still. Here's what I could use some help with

1) Do the menu and modules section feel complete enough? I based it off of the guidelines for the task, but I feel like it's a bit incomplete.
2) Does the guide feel full enough as a whole? Should I add something about adding extensions?

Thanks!

http://www.kahstudios.com/kevin8020/joo ... kstart.odt (NOTE: File is 1.82MB)

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Sat Dec 29, 2007 6:06 am

This is looking REALLY, REALLY good! You know they just released RC 4 on the 19th and that it is expected (hoped!) to be the last RC. So, if that's true, Joomla! v 1.5 is not far off.

Kevin - of all the things you have written in your life, there is likely *nothing* that will be used by as many people as this will be. 8)

++++

INTRO

Add a section in the very front of the guide that informs the reader that they will build an example website:

In this guide, we are creating a website for a pretend landscaping company. The landscaping company wants to make information about trees, bushes and [* spam *] available to site visitors. The president wants a section of the website, as well, to share important plans and reports about the company. In addition, the site must have a way for site visitors to contact the company, search for information, and find links and news feeds relevant to landscaping. The public relations office wants the frontpage to be reserved for specially selected material and needs an RSS feed available for the media.

++++

Back on Step 6 of the Installation - make certain to say - do not install sample data. Then, you know where they are at as you proceed.

++++

After discussing Sections, categories and articles, have them create a products section, and then three categories 1) trees, 2) bushes and 3) grasses category.

Then, a corporate section and a presidents category.

Have them create at least 5 articles in each category with introductory text and main text.

Also, have them select 2 articles from each for the front page.

You don't have to show them this - just instruct them to do it since it will be used in the next section.

++++

Then, show how to configure the User/Contact information - everything that must be done before creating a menu item.

- Show how to create a User (create one for the product manager, the PR director and the president).
- Show how to use the contact manager (categories - just one, then contacts - one for each, above)

++++

Then, show how to create Weblinks - categories/links - one category - and a few links for each

+++

Then, show how to create News feeds - categories/links -one category - and a few feeds for each

++++

Now, we are ready for Menus

Take a moment to introduce more terminology: explain how Joomla! has components, modules and plugins. Components are the main part of the webpage and are driven by menu items. Each Joomla! "webpage" has one component - and there is only one component per Joomla! webpage. Explain that now, after the components have been configured, we can build the menu items that will drive each of the webpages of the site.

For each menu item  (frontpage, article category blog(s), Contact Me, Link Manager, Search Page, Newsfeed) show three things:

A. Explain how to create the menu item.

- From the Menu Item Manager Page, click New.

- Click Articles. Then, Front Page Blog Layout.

B. Show a Picture of the Menu Item Editor for that Menu Item and explain what you want filled out.
- On the Front Page Blog Layout, enter:
  Title: Joomla! Landscaping
    Parameters - Basic
    ....# Leading 1
    ....# Intro 2
    ....# Columns 2
    ....# Links 2
    Parameters - Advanced
    Show a Feed Link Yes.
    Parameters - System
    Page Title - Joomla! Landscaping
        (Make a note that for default content - this is where the soon to be infamous "Welcome to the FrontPage" is.)
  Then, Press Save.

C. Show what it looks like from the front end.

++++

Modules

Explain that modules in Joomla! are not the main part of the page, but are typically the little boxes that surround the main page. Explain how a menu also has a corresponding module - and that it is the module that shows the menu on the front end.

For each module show three things:

A. Explain how to configure it. (Make note of the position of each module - briefly mention how the position is defined in the template.)
B. Show a picture of the module open in the editor. Tell them what to click on and off, etc.
C. Show the module from the front end. Repeat how things you turned on and off impacted the look.

+++

Templates

Add a step where you show the HTML - and show them how a module position is defined in a template. It's okay to say that template development is outside of the scope of the guide, too. But, give them a mental hook for later.

+++

Might want to come back and use the LoadModule plugin to show a module.

+++

Might want to add an extension, too. Maybe a cool GHOP one.

+++

I was very happy when you grabbed this task. It's going to be very important.

Thank you for your work on this.
Amy :)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Sat Dec 29, 2007 10:28 pm

I love the landscape company idea too... gave me ideas about fun stuff I can do with the template section too... cool idea! I'm off to work on this!

WOOT!

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Sat Dec 29, 2007 10:31 pm

You rock! Thanks for this, Kevin, it is going to be GREAT!  8)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Wed Jan 02, 2008 8:56 pm

Quick question - even without installing sample data, the home page link is automatically created... so should I just show how to edit that option, or should I include creation too?

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Wed Jan 02, 2008 11:40 pm

Edit it. Start from that point, I think. 

Just a little background for you - not the guide since this isn't Quick Start stuff, but, the default menu item in Joomla! is sacred. That is what Joomla! uses to know what "homepage" is. So, even in an empty website, there must be one menu and one menu item, marked as "default." If you were to delete that, very bad things would happen. All over the world. I hope you didn't do it, yet.  ;)

Thanks, Kevin, this is going to be really important.

Amy :)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Thu Jan 03, 2008 10:58 pm

Cool... I figured that was the case!

I'm almost done with this draft. I just need to proof it and then I'll have you guys take a look. One note - the beez template is HORRIBLY messed up when using a 2 column layout with 2 leading articles and the newsflash module in the top position... probably would be worth sending the design team after...

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Thu Jan 03, 2008 11:25 pm

Well... with all of those changes, this thing gained some weight... 46 pages now.  I'm open for any and all ideas on how to scrape 20 pages off of this... haha! I'm going back now and doing some reformatting on some sections and cleaning up some. I'll do a spelling and grammar check too - but here's what I've got right now. All input is appreciated:

http://www.kahstudios.com/kevin8020/joo ... kstart.odt (NOTE: File is 4.93MB)
http://www.kahstudios.com/kevin8020/joo ... kstart.pdf (NOTE: File is 3.80MB)

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Thu Jan 03, 2008 11:35 pm

Ok, I'm going to look but first, I am screaming out YEA!!!  :-*

Back after a read...

Amy :)

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Fri Jan 04, 2008 2:30 am

OH MY GOODNESS, KEVIN!!!!  :-*

Yea - that's it! That is IT!

It is really straightforward - gets them BLAZINGLY FAST through almost everything once.  8)

Lovely pictures. Lovely, lovely, lovely and not intimidating at all.

Minor things I would suggest:

When you say "Add a title and alias for the article, and put it into a section". Tell them to not add an alias - as Joomla! will automatically do that for them using the title.

- links give a couple of joomla! examples for links

- newsfeeds give a couple of joomla! examples for rss feeds

- In your menu chapter, create chapter 2 headings with the menu item name

- Page break in front of chapter 1 headings

- Add a table of contents at the front.

It has a wonderfully easy flow - folksy - real life - non technical. You are nailing task, IMO.

Carry on, my friend!
Amy :)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Fri Jan 04, 2008 3:00 am

AmyStephen wrote: OH MY GOODNESS, KEVIN!!!!  :-*

Yea - that's it! That is IT!

It is really straightforward - gets them BLAZINGLY FAST through almost everything once.  8)

Lovely pictures. Lovely, lovely, lovely and not intimidating at all.

Minor things I would suggest:
Thanks! I actually had fun putting this together... with the exception of some of the tedious work... especially photoshoping the menu screenshots
AmyStephen wrote: When you say "Add a title and alias for the article, and put it into a section". Tell them to not add an alias - as Joomla! will automatically do that for them using the title.
Done - good catch!
AmyStephen wrote: - links give a couple of joomla! examples for links

- newsfeeds give a couple of joomla! examples for rss feeds
Not quite sure what you mean here. Are you saying like, "See these sites as examples of Joomla! news feed pages" or "the following are examples of news feeds from Joomla!"
AmyStephen wrote: - In your menu chapter, create chapter 2 headings with the menu item name
Did that there and in modules too, helps a lot...
AmyStephen wrote: - Page break in front of chapter 1 headings
Done!
AmyStephen wrote: - Add a table of contents at the front.
Look again - it's already there  8)
AmyStephen wrote: It has a wonderfully easy flow - folksy - real life - non technical. You are nailing task, IMO.

Carry on, my friend!
Amy :)

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Fri Jan 04, 2008 3:04 am

Kevin8020 wrote:
AmyStephen wrote: - links give a couple of joomla! examples for links

- newsfeeds give a couple of joomla! examples for rss feeds
What I mean is - you indicate all the steps necessary to create a news feed - or a Link - it might be helpful to give one example of the address for the Joomla! RSS feed to paste in. And the URL for joomla.org.

Examples help people understand what they should use.

The RSS feed in particular throws some people.

Regarding "tedious" - yes - these things are not easy to do. That is, in part, why I am really thrilled!

Amy :)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Fri Jan 04, 2008 3:07 am

Ah, alright - thanks!

Oh, one final question... anything in the rules against having my dad edit this for grammar and spelling in the name of open source? ;)

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Fri Jan 04, 2008 3:10 am

Kevin8020 wrote: Ah, alright - thanks!

Oh, one final question... anything in the rules against having my dad edit this for grammar and spelling in the name of open source? ;)
LOL! I think that would be SUPER awesome! Tell him thanks for sharing you with us (and for editiing!)!

Amy :)

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Sat Jan 05, 2008 3:25 am

Mission control, we have quick start:

http://www.kahstudios.com/kevin8020/joo ... kstart.odt (NOTE: File is 5.20MB)
http://www.kahstudios.com/kevin8020/joo ... kstart.pdf (NOTE: File is 4.07MB)

Changes: Lots of spelling stuff, and added in the "search" section which I had completely forgotten about.

AmyStephen
Joomla! Champion
Joomla! Champion
Posts: 7018
Joined: Wed Nov 22, 2006 3:35 pm
Location: Nebraska
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by AmyStephen » Sat Jan 05, 2008 3:33 am

Kevin8020 wrote: Mission control, we have quick start:
You rock!  8)
[me=AmyStephen]curls up to do some of her favorite reading!  :-*[/me]

User avatar
Kevin8020
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 102
Joined: Wed Feb 01, 2006 3:53 am
Location: USA
Contact:

Re: 048 - Create a Joomla! QuickStart Guide

Post by Kevin8020 » Sun Jan 06, 2008 2:48 am

I put you to sleep Amy? ;)


Locked

Return to “Google's Highly Open Participation Contest”