Support Joomla!
Joomla! Documentation Working Group

Joomla! Documentation Blog

Usable, accurate and up-to-date documentation for user and developers is essential. In their blog the leaders of the documentation work group discuss what they do, why they do it and how you can help.

If you are looking for a way to help the documentation effort, then please take a look in the cookie jar where we have a list of s tasks that you can pick up when you have a bit of time and can be completed without too much effort. If you don't feel comfortable writing contents from scratch, we always need people to proofread and copy edit.

Documentation Working Group

The Documentation Working Group is responsible for creating and maintaining all the official Joomla! documentation including that for end-users, administrators and third-party developers. It also maintains the help screens for the Joomla! releases.

The working group maintains these sites:

Discussion of documentation occurs in the documentation forum.



Tue

19

Aug

2008

Mailing list for Doc WG
Written by Marieke van der Tuin   
Tuesday, 19 August 2008 20:20

Not only the Development Working Group and the Joomla! Bug Squad have their own mailing list.. since four days the Documentation Working Group has one as well!

You can find the mailing list at http://groups.google.com/group/joomla-docs/

If you are looking for a way to help the documentation effort, then please take a look in the cookie jar where we have a list of tasks that you can pick up when you have a bit of time left, and can be completed without too much effort. If you don't feel comfortable writing contents from scratch, we always need people to proofread and copy edit. Go have a look at the Documentors profile to read more about it.

 
11 Votes

0 Comments

Fri

18

Jul

2008

Six Ways for Newcomers to Contribute to Joomla!
Written by Mark Dexter   
Friday, 18 July 2008 22:03

Hi there. Although I've been working in the software business over 30 years, I'm a relative newcomer to Joomal!. Many people think you have to be an expert before you can contribute to an open-source project like Joomla!. Well, I don't agree, and so I decided to write down six ways a newcomer can make meaningful contributions to the Joomla! project. Here we go.

1. Help make the "Help" and other entry-level documentation better.

New users are the life blood of an open-source project like Joomla!. We need Joomla! to be as easy as possible for people to learn. As a newcomer, you are "the expert" when it comes to the question of how best to help newcomers learn Joomla!. And it is really easy and quick to provide feedback (both compliments and constructive criticisms) to those of us working on help and documentation.

There is a forum (which is sadly underutilized) under the Documentation / User Documentation / 1.5 Documentation called Suggestions, Modifications, and Corrections. Here is the link: http://forum.joomla.org/viewforum.php?f=391.

What have you found helpful while learning Joomla!? What was missing? What pointers could have saved you a lot of time? Let us know by making a post here and maybe we can make it easier for the next person.

Many Joomla! users (maybe you?) are great writers and communicators. After all, writing and communications are at the heart of most websites. If so, maybe you can contribute an article or a tutorial or just a quick tip. Or even join the documentation team!

Speak a foreign language? Chances are, your translation skills could be greatly needed. Have a tip to share? Make a post in the Tips and Tricks forum.

Hopefully, you get the idea. If you find yourself thinking "I've got to remember that!", think about making a note where everyone can find it.

2. Be a good forum citizen.

The Joomla! forums are very active, friendly, and (in my biased opinion) very helpful. Users of all levels are encouraged to take advantage of this great resource. What has this got to do with helping the Joomla! project, you ask? Plenty. You can help save everyone's time in three easy steps.

  1. Before you post, do a little research to see if your question has already been answered. Use the Handy, dandy search field in the top-right of the forum, and check out the FAQ's and Absolute Beginner's documentation.

  2. When you post, be concise, precise, and nice. Concise: state your question or issue as briefly as possible. Precise: Always say what Joomla! version you are using. If you are having anything that might be system related (like something that seems to work generally isn't working for you), use the Forum Post Assistant to provide your site's technical details in a quick and painless way. Nice: (Do I have to explain that one?)

  3. If your topic comes to a successful conclusion, please go back and edit the first post (if you are the topic starter) to indicate that the issue is solved. Either add "[SOLVED]" to the subject line or use the green check box. Remember, you need to edit the first post for this to be visible from the forum list. This does two things: it tells forum users that there might a good answer in the topic and it tells the people trying to answer questions that they can skip this one.

3. Help on the forums.

Want to learn a lot about Joomla! in a short time? One of the best ways is to help answer questions on the forum. If a topic is interesting but beyond your current knowledge, subscribe to the topic and learn by reading the posts. Many questions can be answered by just by trying something, for example in a local copy of the Joomla! sample website. You can learn something and help someone, all at the same time! Still other questions can be answered with a little research. For example, many questions from newcomers can be answered by pointing them to the correct area of the Joomla! Extensions site. If you're like me and like to read about software products, the Extensions area is a lot of fun. And it's surprisingly easy to download and install extensions and try them out.

Before you know it, you'll be seeing more and more topics where you can help out. Beware: Helping others on the forums can be addictive!

4. Make sure bugs get reported.

If I've learned one thing from my many years in the software business it's this: bugs don't get fixed unless they are reported. Duh! And yet ... how many times have I heard this: "I can't be the only one that has had this problem! The developers must already know about this." Well, maybe you are the "only one", or maybe everyone else is saying the same thing. In either case, it is amazing how many bugs are not fixed for the simple reason that they are never reported. Especially with a program like Joomla!, where it is relatively easy to customize and work around issues, it might be tempting to let others report the bugs. Don't give in to the dark side!

There are three tricks to reporting a bug. The first is to make sure it is a bug. The second is to make sure it can be reproduced in a simple way. The third is to make sure it hasn't already been reported. (Yes, sometimes they have, despite my rant above.)

For simple bugs, the best thing is probably to make a post in the General Questions forum and go from there. There is also a Joomla! 1.5.x_Q&T forum for more complex bugs (for example, bugs you find from the programming side).

Most developers will tell you that the hardest thing about fixing most bugs is being able to reproduce them. Your auto mechanic can't fix that clanging noise in your engine if it's not making it when you take the car to the shop. Likewise, a developer can't fix a bug unless it can be reproduced. I think the best bug report goes something like this: "X doesn't work. To reproduce: (1) Start with Joomla! sample site. (2) Do this, this and this. (3) This should happen, but instead this does." If you can describe a bug in simple terms like this, then it should have a good chance of getting fixed.

5. If you love Joomla!, talk it up.

An easy but effective way to help the Joomla! project is to spread the word. Promote Joomla! on your site, perhaps. Tell your friends. Make Joomla! a friend on your Facebook site. (I'm told you can do this type of thing, although I'm not of the Facebook generation.) Subscribe to the Joomla! announcements forum and participate in Joomla! events. Make comments about it. Blog about it. Open source projects are all about community, and Joomla! has a fantastic community. Be a part of it.

6. Mom, please send money.

If you have more money than time and want to help, the Joomla! project can always use monetary contributions. (The developers have asked me to request that these contributions be made in small, unmarked bills in plain paper envelopes, addressed to them personally.) Seriously, if Joomla! were a commercial product, it would be worth a lot. So do think about this option.

I hope you are convinced that you can contribute in meaningful ways to the Joomla! project even if you are a newcomer. If you do, you'll learn a lot, have lots of fun, meet interesting people, and feel great about helping out.

 

 
8 Votes

2 Comments

Mon

07

Jul

2008

Help screens SQL dump file now available
Written by Chris Davenport   
Monday, 07 July 2008 15:41

The Documentation Working Group is pleased to announce the availability of the recently completed Joomla! 1.5 help screens in the form of an SQL dump of the live help screens hosted on http://help.joomla.org.  The file is available here: http://joomlacode.org/gf/project/joomla/docman/?subdir=6

With this file you can quickly and easily set up a local help server to

  • Serve help screens from a server on your local intranet instead of help.joomla.org.
  • Customise the appearance of the help screens, for example, by adding a corporate logo or using a template that matches your own site style.
  • Use the English help screens as a starting point for a translation of the help screens into another language.

Please read the instructions for setting up a local help server.

The Joomla! 1.5 help screens and the SQL dump file are made available under the terms of the Joomla! Electronic Documentation License.

 
6 Votes

2 Comments

Fri

27

Jun

2008

Help Screens Project
Written by Marieke van der Tuin   
Friday, 27 June 2008 18:07

At the first DocCamp the idea came up that it would be nice to have all Help Screens for 1.5 created, accessible by the Help buttons at the Back-end of your Joomla! site. Four months later, I'm happy to announce that all Help Screens are done, and everyone is able to access all Help Screens at there Joomla! Back-end. The story of an enormous project, with lots of teamwork, discussing, learning and last but not least.. fun!

Google Highly Open Participation contest

It all started with GHOP. During the contest we chatted a lot with each other at the IRC channel. We knew that we did not want to just 'stop' after GHOP. These chats should be continued! Yes, they did, at the Skype Group Chat.

Some GHOPers also joined the Doc Camp, starting at the 19th of January. I did as well (of course), having fun while creating documentation. I choosed to do both Developer Documentation and User Documentation. There my interest began to grow for creating User Documentation, especially the Help Screens.

I noticed a few weeks later, after GHOP was finished, that there had not be any progress anymore on the Help Screens page. Asked Chris Davenport whether I was allowed to go on working them, and of course I could continue.

Help Screens Project

Because there were lots of them to be created, I started to contact some GHOPers, whether they would like to help me. A new project was born! We thought it would be useful to organise a (digital) meeting, to discuss about who will do what, and what would be a useful layout of a Help Screen. Thinking of the idea was much easier than getting it planned. Timezones are really challenging!

After the meeting, we started to work on the Help Screens. There were actually three 'parts' that needed to be completed per Help Screen: Creating (at the Docs), reviewing and moving them to help.joomla.org, so they will be accessible by Joomla!'s Back-end.

It went quite well, but very slow! There are more than 60 Help Screens, and we were working on them with (only) the three of us. Luckily, Mark joined us when we were about halfway. He just came in, without an 'announcement', and we were all suprised. Still remember the PM 'Who is Mark Dexter?' from Max, our reviewer.

Making progress..

With the help of Mark (still wondering how come Mark has that much time), things went faster and faster. A few changes at the SVN had been made to split up some Help Screens, combine them, and to create a few that were missing.

And now.. everything is done! At the end, after four months. How great!

Contributors

I would like to thank everyone who joined the Help Screens Project!

  • Chad Windnagle (drmmr763) for his great ideas and creating some Help Screens
  • Max Shinn (trombonechamp) for reviewing nearly all Help Screens
  • Mark Dexter (dextercowley) for creating Help Screens and moving them to help.joomla.org
  • Chris Davenport (Documentation Working Group Coordinator) for his assistence where needed and for creating a White Paper about the Help Screens
  • Amy Stephen (AmyStephen) for ideas, communication and just being there
  • CirTap for his enormous MediaWiki knowledge
  • Ian MacLennan (ianmac) for fixing keyreferences at the SVN

Without you this project could not have been completed, thanks a lot!

 

Marieke van der Tuin
Project leader 1.5 Help Screens Project

 
10 Votes

8 Comments



Documentation Blog

Latest Wiki Changes