Joomla! Discussion Forums

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



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

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.

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

Thanks igeoffi.
Amy

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.

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

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.

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/

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

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.

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

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

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 -

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

I think you've got it now Amy 

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.

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

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.

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

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

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.

Thanks!

Uploaded to Google Code.

Just for clarification, my name is Geoff, not Chad.

Good grief. 

Thank you Geoff!

Amy