102 - Write a document describing how to set up a local help server.

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!
Geoff
Joomla! Virtuoso
Joomla! Virtuoso
Posts: 3193
Joined: Sun Apr 16, 2006 12:20 am
Location: 127.0.0.1

102 - Write a document describing how to set up a local help server.

Postby Geoff » Mon Dec 17, 2007 10:21 pm

102 - Write a document describing how to set up a local help server.

One line summary
Write a document describing how to set up a local help server.

Description
The document should begin by illustrating, with the aid of screenshots, how
clicking on a help toolbar button in the Administrator will open a window
populated with help information pulled from a remote help server. Then show
how it is possible to point to a different help server by going into Global
Configuration (noting that this is different in 1.0 and 1.5). The document
should then describe how to download the official help screens from
JoomlaCode and install them on a local Joomla! instance (you do not need to
describe how to install Joomla! itself as this is documented elsewhere).

The document should comply with current Joomla! Editorial Style Guidelines
and guidelines for the Template Tutorials Project.

Documentation written for this task must be made available under the
Joomla! Electronic Documentation License.

Skills Needed

Difficulty
Basic.

Work Product
Document as described above.

Extra Credit (optional)
Describe how help screen "key references" are constructed and how to assign
a Joomla! content page to a key reference so it can be retrieved by the
help system.

Time Limit
2 weeks.


Google Task

About Me: Moderately active Joomla! Community member. Been using Joomla! for a while and use it to build/manage most sites now as it saves time (which I don't have much of).

I plan to get  a rough draft/outline done today or tomorrow (depending if I finish some other projects today). Hopefully by the end of this coming weekend I can have a near final draft of this up and ready. My goal is to make the learning process of setting up a local help server as easy as possible.

As usual, comments and questions are always welcome. Criticism is more than welcome (how else would I know what to fix?).

Files: http://frozenfx.com/j102/

updated 1/04/07
Last edited by AmyStephen on Wed Jan 09, 2008 4:05 am, edited 1 time in total.
Backup, backup, backup!
The "Master" .htacess file by Nicholas http://snipt.net/nikosdion/the-master-htaccess

ibnhafsun
Joomla! Hero
Joomla! Hero
Posts: 2318
Joined: Fri Aug 19, 2005 9:41 pm
Contact:

Re: 102 - Write a document describing how to set up a local help server.

Postby ibnhafsun » Tue Dec 18, 2007 1:38 am

If you need some help, just let me know. I haven't been involved with help servers but I could ask someone who has set up one.
...nam qui dabat olim imperium, fasces, legiones, omnia, nunc se continet atque duas tantum res anxius optat, panem et circenses...
http://www.todosjuntos.org
http://inmo-e.com

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

Re: 102 - Write a document describing how to set up a local help server.

Postby AmyStephen » Tue Dec 18, 2007 3:45 pm

Love your goal statement. Perfect! I look forward to learning this!

Thanks igeoffi.
Amy :)

Geoff
Joomla! Virtuoso
Joomla! Virtuoso
Posts: 3193
Joined: Sun Apr 16, 2006 12:20 am
Location: 127.0.0.1

Re: 102 - Write a document describing how to set up a local help server.

Postby Geoff » Wed Dec 19, 2007 1:37 am

I'm not sure if I'm not seeing things but this is the latest sql dump correct?
http://joomlacode.org/gf/project/joomla ... /?subdir=6
(help_screens_translation_pack_090307-v1.1.zip)

I just want to make sure nothing else is available somewhere else and I'm missing it.
Backup, backup, backup!
The "Master" .htacess file by Nicholas http://snipt.net/nikosdion/the-master-htaccess

User avatar
ianmac
Joomla! Virtuoso
Joomla! Virtuoso
Posts: 4785
Joined: Sat Sep 24, 2005 11:01 pm
Location: Toronto, Canada

Re: 102 - Write a document describing how to set up a local help server.

Postby ianmac » Fri Dec 21, 2007 10:01 pm

That is the latest dump we have.  The actual data isn't as important as documenting the process of setting the server up.  Let us know if you have further questions.

Ian

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

Re: 102 - Write a document describing how to set up a local help server.

Postby Chris Davenport » Fri Dec 21, 2007 11:13 pm

That file is for the 1.0.x help screens.  We don't yet have a dump file for the 1.5 help screens, but the principle remains the same.

It is probably a good idea to briefly explain how the key references work and in particular explain that the Joomla! version number is added as a suffix.  For example, a screen called "screen.config" in the 1.0.x series, will now need to have a key reference of "screen.config.15" for Joomla! 1.5.x.

If you have any questions, just shout.

Regards,
Chris.
Chris Davenport - Joomla Production Leadership Team

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

Geoff
Joomla! Virtuoso
Joomla! Virtuoso
Posts: 3193
Joined: Sun Apr 16, 2006 12:20 am
Location: 127.0.0.1

Re: 102 - Write a document describing how to set up a local help server.

Postby Geoff » Sat Dec 22, 2007 10:51 pm

Rough draft 1.
Note: screenshots are more like placeholders. I will take better screenshots soon. Some steps are missing screenshots. The steps towards the end aren't completed in full detail yet.

Files: http://frozenfx.com/j102/
Backup, backup, backup!
The "Master" .htacess file by Nicholas http://snipt.net/nikosdion/the-master-htaccess

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

Re: 102 - Write a document describing how to set up a local help server.

Postby AmyStephen » Thu Dec 27, 2007 1:31 am

OK. I followed the instructions - and I am a good test case because I have no idea about how to set up a local help server.

Trouble is, even after installing v 1.0.13 without the default data; opening up the SQL files, changing #_ to jos_, and importing the SQL, it still appears my installation help files point to help.joomla.org.

What is missing from these instructions for me is *where* are the local help files? How can I update these files? How can I create an install so that all of my end users access this help environment?

Don't worry, though! You are in great luck - you have the perfect test case in me. When I know how to do this, you will have moved mountains and achieved great work!

Be encouraged - and give me more to go on!
Amy :)

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

Re: 102 - Write a document describing how to set up a local help server.

Postby Chris Davenport » Thu Dec 27, 2007 12:07 pm

Hi Amy,

Your plight highlights a few things that need to be added to the document.  ;)

There needs to be an introduction that explains what a local help server is and why you might want to set one up.  Amy, you seem to be confusing this with the local help files (the ones actually distributed with Joomla!).  The "local help server" is a separate instance of Joomla! running on your LAN (could be on the same machine, but doesn't have to be).  This is useful, for example, if you only have an expensive dial-up connection to the internet, or you are running on a closed intranet with no access to the public internet. In effect it is a partial clone of help.joomla.org.

The other problem is that we are between versions and so the instructions cannot work right now anyway.  :)

The 1.0.x help screens and the 1.5.x help screens are entirely separate.  The document we wanted to create was about how to set up a help server to service instances of 1.5.  But right now the only help screens available are for 1.0.x running on a 1.0.x instance.  If you were to point a 1.5 instance at such a help server you would get "Key not found" errors for all the help buttons.

Once the 1.5 help screens have been written we will make a 1.5 help screen dump file available, but initially this will still need to run on a 1.0.x instance.  The step after that will be to migrate the data so that you can set up a local help server running 1.5.x.

There needs to be some instructions on how to add your local help server address to the helpsite XML file and having done so, how to get Joomla! to use the new entry.

I also think it would be nice to give some information on how the help screen "key references" work.  In other words, how clicking on a help toolbar button in Joomla! 1.5 with a key reference of "screen.config", say, is used to retrieve the article on the help server with key reference "screen.config.15" (note that the version number is appended to the key reference, except for 1.0.x).  So when we start working on 1.6 the key reference will automatically become "screen.config.16".

Hope this helps.

Regards,
Chris.
Chris Davenport - Joomla Production Leadership Team

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

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

Re: 102 - Write a document describing how to set up a local help server.

Postby AmyStephen » Thu Dec 27, 2007 5:00 pm

Yes, I am the perfect test case for this document since I have not a clue!  :P

I realize we don't have v 1.5 ready - so, setting that topic aside for a moment, I followed the instructions for v 1.0.13.

But, I expected when I clicked on the Help to navigate to my local resource, not help.joomla.org . Is that what I should have expected?

Thanks much!
Amy :)

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

Re: 102 - Write a document describing how to set up a local help server.

Postby Chris Davenport » Thu Dec 27, 2007 8:31 pm

You mean you want a 1.0.x instance to point to a 1.0.x local help server?

Just go into Global Configuration, Server tab.  Enter the URL for your local Help Server.  Should work fine.

Chris.
Chris Davenport - Joomla Production Leadership Team

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

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

Re: 102 - Write a document describing how to set up a local help server.

Postby AmyStephen » Fri Dec 28, 2007 5:01 am

Chris -

Should that instruction that you just gave me be in this document? Or, am I misunderstanding this task?

OK - I'm looking into the content items, now, and I think I finally get it. The screens are the content items.

When I change the content item, I get the updated help screen.

The way they point to the local help is to point to the URL of this help server I just installed given Chad's instructions.

Sorry to be so dense! When Chad returns later this week, it might be good to add some of this obviousness into the text. (I'm certain there is at least one other person as out of touch as I am!  ;) )

Amy

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

Re: 102 - Write a document describing how to set up a local help server.

Postby Chris Davenport » Fri Dec 28, 2007 12:45 pm

I think you've got it now Amy  :D

Yes, I think this stuff needs to be explained in the document.  I didn't understand how it all worked until I read the code either.  It's not obvious.

Chris.
Chris Davenport - Joomla Production Leadership Team

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

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

Re: 102 - Write a document describing how to set up a local help server.

Postby AmyStephen » Fri Dec 28, 2007 6:18 pm

Now that I understand the task a bit more, I'll be of more help. Chad's got a great start on this. He's "at the mountains" this week (lucky guy!). When he returns, we can continue working on this.

Thanks, Chris!
Amy :)

Geoff
Joomla! Virtuoso
Joomla! Virtuoso
Posts: 3193
Joined: Sun Apr 16, 2006 12:20 am
Location: 127.0.0.1

Re: 102 - Write a document describing how to set up a local help server.

Postby Geoff » Sat Jan 05, 2008 6:36 pm

Updated:
Files: http://frozenfx.com/j102/

Sorry it took so long. I decided to bring my laptop with me on vacation, installed a sprint network card to get internet access on the road, and in the process killed my laptop and all its files through some bad driver update.

Final reviews appreciated.
Backup, backup, backup!
The "Master" .htacess file by Nicholas http://snipt.net/nikosdion/the-master-htaccess

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

Re: 102 - Write a document describing how to set up a local help server.

Postby AmyStephen » Tue Jan 08, 2008 4:33 am

Page 2 - instllations - installations

Other than that, the instructions helped me to install v 1.0.13 help.

I accept this as complete. Since it's so critical for the Doc Team, I want Chris or Ian to provide final approval.

Thanks Chad for this great work,
Amy :)

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

Re: 102 - Write a document describing how to set up a local help server.

Postby AmyStephen » Tue Jan 08, 2008 6:53 am

One more thing - everyone is so very busy right now. If you have not heard from Chris or Ian in the next 24 hours, please, give this thread a bump and I'll finalize the document.

Thanks!
Amy :)

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

Re: 102 - Write a document describing how to set up a local help server.

Postby Chris Davenport » Tue Jan 08, 2008 4:42 pm

Hi Chad,

Sorry, it's taken a while.  As Amy has said, we are under a bit of pressure at the moment.  ;)

Anyway, I think this is excellent work and I'm sure that many people will find it useful as it takes the mystique out of setting up your own local help server.

Please upload the finished work to the Google issue tracker if you haven't already.  Amy will close the task as soon as you have done that and you are free to choose another task if you wish.

Thanks for all the hard work.  :)

Regards,
Chris.
Chris Davenport - Joomla Production Leadership Team

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

Geoff
Joomla! Virtuoso
Joomla! Virtuoso
Posts: 3193
Joined: Sun Apr 16, 2006 12:20 am
Location: 127.0.0.1

Re: 102 - Write a document describing how to set up a local help server.

Postby Geoff » Wed Jan 09, 2008 3:32 am

Thanks!

Uploaded to Google Code.

Just for clarification, my name is Geoff, not Chad. :D
Backup, backup, backup!
The "Master" .htacess file by Nicholas http://snipt.net/nikosdion/the-master-htaccess

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

Re: 102 - Write a document describing how to set up a local help server.

Postby AmyStephen » Wed Jan 09, 2008 3:58 am

Good grief.  :-[

Thank you Geoff!

Amy :)


Return to “Google's Highly Open Participation Contest”

Who is online

Users browsing this forum: No registered users and 0 guests