104 - Write a document explaining how to create a custom HTML module

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!
Locked
blitzprog
Joomla! Apprentice
Joomla! Apprentice
Posts: 9
Joined: Fri Nov 30, 2007 2:52 pm
Location: Garbsen
Contact:

104 - Write a document explaining how to create a custom HTML module

Post by blitzprog » Fri Nov 30, 2007 3:51 pm

Hello,

my name is Eduard Urbach and I'm 16 years old. I come from Germany (Hannover) and I like open source software because I think it's better than proprietary software. My preferred IDE is Eclipse which is also my favourite IDE for C++ projects on Ubuntu Linux - my favourite operating system. I used Joomla 1.0 in one web project but I've never used Joomla 1.5 before.

Three questions:
1.) Should I just describe how to create a module with some HTML code in it?
2.) Can I use screenshots in the document?
3.) Which format? I'll write it in Open Office 2.3. Would that be okay? [edited] Okay, as far as I can see ODT is the right format.

My task:
==One line summary==
Write a document explaining how to create a custom HTML module.

==Description==

For this task you will help beginning users move beyond the basics to take
advantage of the flexibility of Joomla!.

Create a one page document that describes the steps for the module manager
to create a custom HTML module in Joomla! 1.5.

== Skills Needed==
* Familiarity with Joomla!
* Good writing skills
* Good page layout skills

== Difficulty==

Basic

==Work Product==

A one page polished  document that effectively explains the process to a
beginning user.

==Licensing==
{{doclicense}}

==Extra Credit (optional)==

Create a document that explains how to create a new position in the module
manager and how to use the loadposition plug-in  to insert a module into
content.

==Time Limit==

Two weeks
Claimed: Nov 30 Due: Dec 14

Google Task

[me=AmyStephen]Changed subject slightly for sorting all threads to match against Google resource  :)[/me]
Last edited by AmyStephen on Tue Dec 11, 2007 6:40 pm, edited 1 time in total.

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: 104 - Write a document explaining how to create a custom HTML module

Post by Chris Davenport » Fri Nov 30, 2007 6:11 pm

Hi Eduard,
blitzprog wrote: 1.) Should I just describe how to create a module with some HTML code in it?
Yes.  Maybe choose a scenario which occurs frequently so readers can immediately relate to the task that is being described.
blitzprog wrote: 2.) Can I use screenshots in the document.
Yes.  Not only do they "tell a thousand words", they also give the reader a visual check on what they are doing.  They can also help the reader "preview" the outcome of a procedure making it easier for the reader to select the right procedure for the task they are facing.  Just be careful not to overwhelm the reader with too many screenshots though.  You don't necessarily need a screenshot for every single step or keystroke.
blitzprog wrote: 3.) Which format? I'll write it in Open Office 2.3. Would that be okay? [edited] Okay, as far as I can see ODT is the right format.
Yes, OpenOffice format would be ideal.

Thanks for taking up the challenge.  Good luck with your task!

Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

blitzprog
Joomla! Apprentice
Joomla! Apprentice
Posts: 9
Joined: Fri Nov 30, 2007 2:52 pm
Location: Garbsen
Contact:

Re: 104 - Write a document explaining how to create a custom HTML module

Post by blitzprog » Fri Nov 30, 2007 6:27 pm

Download

I'd like to hear some feedback because I don't know whether this is okay. English is not my native language so it is very probable that I've made some mistakes. I haven't used only one page, I've used five pages because the screenshots would be too small if they were on one page only. Tomorrow I'll maybe add an HTML example with "a scenario which occurs frequently".

Which license should it be? I don't know what "doclicense" means, "documentation license"? Where can I get the license text? [edited] Is it this one?
Last edited by blitzprog on Fri Nov 30, 2007 6:43 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: 104 - Write a document explaining how to create a custom HTML module

Post by trombonechamp » Sat Dec 01, 2007 1:07 am

There were hardly any problems with grammar that I noticed.  The only ones I found were the following:

- There are two number 1s  :D
- Under number 3, it says "As you want to create a new module".  I think it would be "Since you want to create a new module"
- "This was easy, wasn't it?" should be "That was easy", because it is the past tense.

Good luck!
Leonard Bernstein for President -
Web Development Services: www.BernsteinForPresident.com
My Software Freedom Blog: Trombonechamp.Wordpress.com

blitzprog
Joomla! Apprentice
Joomla! Apprentice
Posts: 9
Joined: Fri Nov 30, 2007 2:52 pm
Location: Garbsen
Contact:

Re: 104 - Write a document explaining how to create a custom HTML module

Post by blitzprog » Sat Dec 01, 2007 8:56 am

Thank you :) Here's the new version:
Download

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: 104 - Write a document explaining how to create a custom HTML module

Post by Chris Davenport » Sat Dec 01, 2007 9:49 am

blitzprog wrote: Which license should it be? I don't know what "doclicense" means, "documentation license"? Where can I get the license text? [edited] Is it this one?
Yes, that's the one.  {{doclicense}} is a bit of wiki syntax that should have been expanded.  Apologies for that.

Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

blitzprog
Joomla! Apprentice
Joomla! Apprentice
Posts: 9
Joined: Fri Nov 30, 2007 2:52 pm
Location: Garbsen
Contact:

Re: 104 - Write a document explaining how to create a custom HTML module

Post by blitzprog » Sat Dec 01, 2007 10:38 am

Okay, I added the License in pdf and txt format.
Do I have to do anything else? :)
Last edited by blitzprog on Sat Dec 01, 2007 10:40 am, edited 1 time in total.

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

Re: 104 - Write a document explaining how to create a custom HTML module

Post by AmyStephen » Sun Dec 02, 2007 6:50 am

GHOP Contestants Please Read: Task Process Start to Finish for important updates on the contest.


blitzprog - After reading the link from above, please let us know if you are calling for a final review!

blitzprog
Joomla! Apprentice
Joomla! Apprentice
Posts: 9
Joined: Fri Nov 30, 2007 2:52 pm
Location: Garbsen
Contact:

Re: 104 - Write a document explaining how to create a custom HTML module

Post by blitzprog » Sun Dec 02, 2007 1:08 pm

I call for a final review:
Download

If there are some grammar mistakes please let me know.

User avatar
drmmr763
Joomla! Ace
Joomla! Ace
Posts: 1671
Joined: Tue Oct 23, 2007 8:51 pm
Location: Orlando, Florida
Contact:

Re: 104 - Write a document explaining how to create a custom HTML module

Post by drmmr763 » Mon Dec 03, 2007 2:27 am

I was just reading through your tutorial. I notice that when you create the module you use straight HTML into the HTML editor. I think it would be good if you also showed people that they can insert the image(s) using the WYSIWYG editor.
-Chad Windnagle
Please use the search feature as your question might already have been answered.

http://www.s-go.net/ ~ Website Hosting - Strategic Marketing - Website Development - Print Work

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

Re: 104 - Write a document explaining how to create a custom HTML module

Post by trombonechamp » Mon Dec 03, 2007 1:53 pm

I don't see any grammar mistakes!
I do agree with Chad in the fact that you should show them they can edit the HTML in TinyMCE.  You don't even have to give a full tutorial of the editor, but maybe put a note in there that mentions that you can still edit using TinyMCE.

Hope this helps!
Leonard Bernstein for President -
Web Development Services: www.BernsteinForPresident.com
My Software Freedom Blog: Trombonechamp.Wordpress.com

blitzprog
Joomla! Apprentice
Joomla! Apprentice
Posts: 9
Joined: Fri Nov 30, 2007 2:52 pm
Location: Garbsen
Contact:

Re: 104 - Write a document explaining how to create a custom HTML module

Post by blitzprog » Mon Dec 03, 2007 2:54 pm

Thank you for reading it :)

But I don't agree with you. I think there should be one good tutorial explaining the advantages of the WYSIWYG editor.
If there will be such a task in the contest, I'll do it :)
If there is already a tutorial about this subject I could add a link in my document.

By the way, I think there should be more "programmng tasks" in the contest.
I normally don't like it to write a documentation for a program where I didn't participate as a programmer.
Just my opinion ;)

One question to the list of tasks:
What is a "unit test plan"? Is it a test for a specificic part of program, e.g. a single module?

[edited] I think I finished the task. Could someone please change the status of this task to "Under Review"?
Last edited by blitzprog on Mon Dec 03, 2007 3:03 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: 104 - Write a document explaining how to create a custom HTML module

Post by AmyStephen » Tue Dec 04, 2007 6:01 am

That was very good. Straight-forward. Easy to follow. Nice numbered points.

I'd recommend page numbers and a page title, otherwise, it looks very good to me.

Any others wanting to assist with a Final Review - your help is appreciated!
Amy :)

blitzprog
Joomla! Apprentice
Joomla! Apprentice
Posts: 9
Joined: Fri Nov 30, 2007 2:52 pm
Location: Garbsen
Contact:

Re: 104 - Write a document explaining how to create a custom HTML module

Post by blitzprog » Wed Dec 05, 2007 4:34 pm

I'd recommend page numbers and a page title
Update:
Download

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: 104 - Write a document explaining how to create a custom HTML module

Post by Chris Davenport » Wed Dec 05, 2007 6:41 pm

Hi Eduard,

I think this is good work and you are definitely on the right track.

I'd like to see the images cropped.  Graying out most of each image to highlight the area of interest is good, but in most cases this leaves a large image which is mostly gray.  Most of them can be cropped while still retaining enough context for the reader to understand what is being illustrated.  Also, by cropping the images they will take up less space on the page and this will probably enable you to break away from having only two images per page and leaving a large amount of white space.  Take a look at Chad's entry and you will see the difference it can make.

Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

blitzprog
Joomla! Apprentice
Joomla! Apprentice
Posts: 9
Joined: Fri Nov 30, 2007 2:52 pm
Location: Garbsen
Contact:

Re: 104 - Write a document explaining how to create a custom HTML module

Post by blitzprog » Thu Dec 06, 2007 5:55 pm

I'd like to see the images cropped.
Update:
Download
Last edited by blitzprog on Sat Dec 08, 2007 8:57 am, edited 1 time in total.

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

Re: 104 - Write a document explaining how to create a custom HTML module

Post by AmyStephen » Tue Dec 11, 2007 6:38 pm

blitzprog -

Please post this on Google and we will finalize your task.

Thanks!
Amy :)


Locked

Return to “Google's Highly Open Participation Contest”