Page 1 of 1

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

Posted: Mon Dec 17, 2007 10:21 pm
by Geoff
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

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

Posted: Tue Dec 18, 2007 1:38 am
by ibnhafsun
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.

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

Posted: Tue Dec 18, 2007 3:45 pm
by AmyStephen
Love your goal statement. Perfect! I look forward to learning this!

Thanks igeoffi.
Amy :)

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

Posted: Wed Dec 19, 2007 1:37 am
by Geoff
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.

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

Posted: Fri Dec 21, 2007 10:01 pm
by ianmac
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

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

Posted: Fri Dec 21, 2007 11:13 pm
by Chris Davenport
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.

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

Posted: Sat Dec 22, 2007 10:51 pm
by Geoff
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/

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

Posted: Thu Dec 27, 2007 1:31 am
by AmyStephen
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 :)

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

Posted: Thu Dec 27, 2007 12:07 pm
by Chris Davenport
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.

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

Posted: Thu Dec 27, 2007 5:00 pm
by AmyStephen
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 :)

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

Posted: Thu Dec 27, 2007 8:31 pm
by Chris Davenport
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.

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

Posted: Fri Dec 28, 2007 5:01 am
by AmyStephen
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

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

Posted: Fri Dec 28, 2007 12:45 pm
by Chris Davenport
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.

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

Posted: Fri Dec 28, 2007 6:18 pm
by AmyStephen
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 :)

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

Posted: Sat Jan 05, 2008 6:36 pm
by Geoff
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.

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

Posted: Tue Jan 08, 2008 4:33 am
by AmyStephen
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 :)

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

Posted: Tue Jan 08, 2008 6:53 am
by AmyStephen
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 :)

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

Posted: Tue Jan 08, 2008 4:42 pm
by Chris Davenport
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.

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

Posted: Wed Jan 09, 2008 3:32 am
by Geoff
Thanks!

Uploaded to Google Code.

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

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

Posted: Wed Jan 09, 2008 3:58 am
by AmyStephen
Good grief.  :-[

Thank you Geoff!

Amy :)