Actions

JDOC

Difference between revisions of "How to Contribute to Joomla! Documentation"

From Joomla! Documentation

m (What you need: updates)
m (Create a User Page: updates)
(17 intermediate revisions by one user not shown)
Line 1: Line 1:
=Introduction=
 
If you are reading this page, the Docs Team hopes you will take the next steps to maintaining, improving and contributing to the Joomla! Project's Documentation. Our documentation is written by users, developers, and code contributors for the benefit of the same. There are many Open Source Projects using Mediawiki software succesfully for their project's documentation. The Mediawiki software allows for open collaboration, version control of pages, tracking changes similar to Git and a large base of extensions to extend the user interface. A wiki is '''hard to break''' with page history. Make a mistake and just undo or revert the page back to the previous version.
 
  
==What you need==
+
Joomla! Documentation is powered by the same [[wp:wiki|software used by Wikipedia]]. It's growth and success is dependent on [[Special:ActiveUsers|individuals like you]]. Thank you for taking the first step towards contributing to the Joomla! Project. This page will show you how to get started and several ways of helping the documentation effort.  
* To edit the Joomla! Documentation Wiki, you will need a user account. If you don't already have one, you may '''[[Special:UserLogin|register for one here]]'''. All a willing contributor needs is a valid email address to register. After confirming your email address you will have immediate permission to edit any page except for a few that are protected because they are high profile spam targets or high web traffic.
+
* '''Important!''' - You should review the Joomla! Docs '''[[JDOC:Wiki policy|Wiki policy]]''' before you start editing.
+
* If you want to edit a page but you're not sure what to write exactly, use talk pages to add comments to pages. Alternatively, you can join the '''[http://groups.google.com/group/joomla-docs Docs mail list]'''.
+
  
==Help, I don't know Wiki Markup!==
+
==Getting Started!==
 +
There are a few things you will need to do first.
 +
====Read the Wiki Policy====
 +
:You need to review the Joomla! Docs '''[[JDOC:Wiki policy|Wiki policy]]''' before you start editing.
 +
====Create a User Account====
 +
:To edit the Joomla! Documentation Wiki, you will need a user account. You may '''[[Special:UserLogin|register for one here]]'''. After confirming your email address you will have immediate permission to edit any page except for a few that are protected.
 +
====Create a User Page====
 +
:After you have created an account, confirmed your email address and logged in, you should create a user page. A quick cheat to start your user page:
 +
*actions drop down
 +
*create
 +
*add the code to editor<code><nowiki>{{subst:Newuser}}</nowiki></code>
 +
*fill in summary (e.g. my new user page)
 +
*save
  
If you are new to the use of '''''Wikis''''' and the simple markup to create pages, then you can use the following for help.
+
====Join the Documentation Mail List====
*New WikiEditor contains buttons and quick links to make building pages easier. Click the word ''''Advanced'''' for a drop down of more buttons and quick formatting links.
+
: You should join the '''[http://groups.google.com/group/joomla-docs Docs mail list]'''. It is not required but there are discussions you will miss out on which are relevant to documentation.
*Use the [[Help:Cheatsheet|JDOC's Wiki Cheatsheet]] to learn the basic syntax commands. There is also a drop down of the common markup in the editor. Just click the word ''''Help'''' once and it will appear.
+
*Still afraid? Try these tools to help you create great wiki pages.
+
:*[http://www.microsoft.com/en-us/download/details.aspx?id=12298 Microsoft Word Add-on for Wiki Markup], save Word Docs in Wiki Markup.
+
:*'''OpenOffice.org versions 2.4 and later''' have a MediaWiki export filter built in. Just open a Writer document and click File - Export. Then, change File format to MediaWiki.
+
:*Here is a [[wp:Wikipedia:Tools#Importing_.28converting.29_content_to_Wikipedia_.28MediaWiki.29_format|list of tools]] available to convert other formats to wiki markup, e.g. HTML, Excel, CSV. Some of them are online converters, cut and paste HTML for an output in wiki markup.
+
*Get help on the [http://groups.google.com/group/joomla-docs Joomla! Documentation Mail List] by posting a question.
+
*Post a question on an administrator's or editor's talk page.
+
  
=Where do I start?=
+
==What Should I Do First?==
==Jump right in==
+
There are several areas of documentation which always need attention. You can start by picking the one which is the most comfortable for you to work on or you may get more involved by working on several at a time. Once you have a wiki account, you are free to work on any aspect of the documentation that takes your fancy. Even the simplest contributions such as spelling corrections and grammar fixes are a tremendous help!
Once you have a wiki account, you are free to work on any aspect of the documentation that takes your fancy. Don't worry, sometimes even the most seasoned wiki editors can get lost, distracted or confused about what to do next. Even the simplest contributions such as spelling corrections and grammar fixes are a tremendous help!  
+
#[[#Help Manage Our Content|Help with documentation content]].
 +
#[[#Wiki Maintenance|Maintenance Tasks]].
 +
#[[#Documentation Project|Join or start documentation project]].
 +
#[[#Help Screens|Help with Help Screens]].
 +
===Help Manage Our Content===
  
==Specific tasks==
+
#Editing, rewriting and reorganising pages. Check our [[:Category:Joomla!_Wiki_need_pages|Needs pages]] for areas needing immediate help. They are called 'Needs pages' because they are in need of small tasks to complete them. Some of them are as simple as reviewing content or adding an image. Others require more content or improvements. Pick a few, give them a little love. This is a tremendous help to Joomla! users who rely on our documentation.
Here are just a few suggestions below that really need some love and attention.  
+
#Have some fun and browse for articles which are redundant, out of version(i.e. 1.0 and 1.5), or need to be split up because of version specific information. Then feel free to make use of the {{tl|delete}}, {{tl|merge}} or {{tl|JSplit}} templates on the articles. ''Click the previous template links to see how to use and apply them to articles you think need these marker templates. Add them to the very top of a page and the page is marked.''
 +
#[[JDOC:Creating New Content|Create a new page or tutorial]]. If you want to start a new page, do some extensive research first. Try not to create a new article if one already exists. Use the [[Special:GoogleCustomWikiSearch|search feature]] of the Docs Wiki to see if your topic is already in an article. '''Duplication will be merged and/or deleted'''. Don't be afraid to modify, reformat or improve someone else's work on the Joomla! Docs Wiki! This is a collaborative documentation wiki, just make sure you are following our [[JDOC:Policies and guidelines|policy and guidelines]].
  
*Check the ''''[[:category:Cookie jar|Cookie jar]]'''' - The Docs Team loves an empty 'cookie jar' so please grab a cookie and make it disappear.
+
===Wiki Maintenance===
*Have some fun and browse for articles which are redundant, out of version(i.e. 1.0 and 1.5), or need to be split up because of version specific information. Then feel free to make use of the {{tl|delete}}, {{tl|merge}} or {{tl|JSplit}} templates on the articles. ''Click the previous template links to see how to use and apply them to articles you think need these marker templates. Add them to the very top of a page and the page is marked.''
+
:Maintaining a wiki and keeping it organised takes a lot of continuous work on the part of administrators, editors and users. There are always tasks needing attention such as: [[Special:UncategorizedPages|Categorisation]], [[:Category:Joomla!_Wiki_need_pages|attending to pages with needs]] or marking pages for [[Template:Delete|deletion]], [[Template:Merge|merging]] or [[Template:JSplit|splitting]]. For all maintenance tasks and ideas of how you can help, please visit our [[JDOC:Maintenance Tasks|Documentation Maintenance page]].
*Another area of similar to the 'Cookie jar' is our [[:Category:Joomla!_Wiki_need_pages|Needs pages]]. They are called 'Needs pages' because they are in need of various tasks to complete them. Some of these needs are simple tasks such as reviewing content, adding an image, more content or improvements. Pick a few, give them a little love. This is a tremendous help to Joomla! users who rely on and read the docs.
+
 
*Categorisation is always a something easy to do, necessary and in great demand on our wiki! [[Special:UncategorizedPages|Pages without categories]] are abundant, pick some titles you know and skip the ones you might not know right off. Categories are important because they help define the structure of the wiki and make it easier to find articles.
+
===Documentation Projects===
*The docs team is also working on [[Beginner Tutorials]]. Our goal is to make them easy to understand and navigate, something a Beginner can follow easily and learn basic concepts. Think back to when you were new to Joomla! and add a topic about something you struggled with as a beginner.
+
*The docs team is working on [[Tutorials:Beginners|Beginner Tutorials]]. Our goal is to make them easy to understand and navigate, something a Beginner can follow easily and learn basic concepts. Think back to when you were new to Joomla! and add a topic about something you struggled with as a beginner to the page. Better yet, join the [[JDOC:Beginners_Tutorial_Project|Beginner Tutorials Project]].
*Help pages, yes we know they are a lot of work, but necessary for beginners and even those with intermediate knowledge of Joomla! '''The Joomla! 2.5 Help Screens are complete''' but Joomla! 3.x are still being worked on! The contributions you give to them will be appreciated by many users worldwide. You can find the matrix of [[Help31:Help_screens|3.x Help Screens here]]. Some just need to be reviewed and marked complete in status, others need to be started, completed, have images uploaded(670px max width), etc. {{dablink|Please read the [[Help31:Help_screens_styleguide|3.x Help Screens Style Guide]]. Help Screens are seen by many users worldwide, so '''it is important to maintain a similar style'''.}}
+
 
*Join the [[JDOC:Developer Tutorials Project|Developer Tutorials Project]] and share your knowledge. Sign your name using 4 tildes ( <nowiki>~~~~</nowiki> ) on the [[JDOC_talk:Developer Tutorials Project|Developer Tutorials Project]] page and list what you might be able to do. Feel free to add some [[JDOC:Developer Tutorials Project/Topics|tutorial topics]] to the suggested topics list.
 
*Join the [[JDOC:Developer Tutorials Project|Developer Tutorials Project]] and share your knowledge. Sign your name using 4 tildes ( <nowiki>~~~~</nowiki> ) on the [[JDOC_talk:Developer Tutorials Project|Developer Tutorials Project]] page and list what you might be able to do. Feel free to add some [[JDOC:Developer Tutorials Project/Topics|tutorial topics]] to the suggested topics list.
  
=Things to Remember=
+
===Help Screens===
 +
 
 +
Unknown to many, all [[Help screens|Help Screen]] pages are created and served to every Joomla! Installation worldwide from this wiki! They are necessary for beginners and even those with intermediate knowledge of Joomla!
 +
 
 +
:'''The Joomla! 2.5 Help Screens are complete''' but Joomla! 3.x are still being worked on! The contributions you give to them will be appreciated by many users worldwide. You can find the matrix of [[Help31:Help_screens|3.x Help Screens here]]. Some just need to be reviewed and marked complete in status, others need to be started, completed, have images uploaded(670px max width), etc. {{dablink|Please read the [[Help31:Help_screens_styleguide|3.x Help Screens Style Guide]]. Help Screens are seen by many users worldwide, so '''it is important to maintain a similar style'''.}}
 +
 
 +
==Things to Remember==
 
Here a a few things to remember as a Joomla! Docs contributor.
 
Here a a few things to remember as a Joomla! Docs contributor.
  
 +
*Don't be afraid to break a page, if you do and something has gone really wrong, revert your edit. Click the page's '''View History''' tab and you will see links to undo and revert.
 
*Write articles with a sense they will translated to another language. Using slang or local dialect may not translate to another language or its inferences be understood.
 
*Write articles with a sense they will translated to another language. Using slang or local dialect may not translate to another language or its inferences be understood.
 
*Don't be afraid to download and read the general [http://help.joomla.org/files/Editorial%20Style%20Guide%20v1.0.5.pdf Editorial Style Guide] (PDF) that applies to all Joomla! Documentation. There are helpful hints on how to write for Joomla! Documentation.
 
*Don't be afraid to download and read the general [http://help.joomla.org/files/Editorial%20Style%20Guide%20v1.0.5.pdf Editorial Style Guide] (PDF) that applies to all Joomla! Documentation. There are helpful hints on how to write for Joomla! Documentation.
Line 42: Line 53:
 
*Don't forget to add the {{tl|inuse}} template to an article you are going to be working on for a long period of time, more than a minute. It helps to prevent editing conflicts.
 
*Don't forget to add the {{tl|inuse}} template to an article you are going to be working on for a long period of time, more than a minute. It helps to prevent editing conflicts.
  
<headertabs/>
+
==Help, I don't know Wiki Markup!==
 +
If you are new to the use of '''''Wikis''''' and the simple markup to create pages, then you can use the following for help.
 +
*New WikiEditor contains buttons and quick links to make building pages easier. Click the word ''''Advanced'''' for a drop down of more buttons and quick formatting links.
 +
*Use the [[Help:Cheatsheet|JDOC's Wiki Cheatsheet]] to learn the basic syntax commands. There is also a drop down of the common markup in the editor. Just click the word ''''Help'''' once and it will appear.
 +
*Still afraid? Try these tools to help you create great wiki pages.
 +
:*[http://www.microsoft.com/en-us/download/details.aspx?id=12298 Microsoft Word Add-on for Wiki Markup], save Word Docs in Wiki Markup.
 +
:*'''OpenOffice.org versions 2.4 and later''' have a MediaWiki export filter built in. Just open a Writer document and click File - Export. Then, change File format to MediaWiki.
 +
:*Here is a [[wp:Wikipedia:Tools#Importing_.28converting.29_content_to_Wikipedia_.28MediaWiki.29_format|list of tools]] available to convert other formats to wiki markup, e.g. HTML, Excel, CSV. Some of them are online converters, cut and paste HTML for an output in wiki markup.
 +
*Get help on the [http://groups.google.com/group/joomla-docs Joomla! Documentation Mail List] by posting a question.
 +
*Post a question on an administrator's or editor's talk page.
 +
 
  
 
[[Category:Documentation Wiki Information]]
 
[[Category:Documentation Wiki Information]]

Revision as of 12:55, 10 November 2013

Joomla! Documentation is powered by the same software used by Wikipedia. It's growth and success is dependent on individuals like you. Thank you for taking the first step towards contributing to the Joomla! Project. This page will show you how to get started and several ways of helping the documentation effort.

Contents

Getting Started!

There are a few things you will need to do first.

Read the Wiki Policy

You need to review the Joomla! Docs Wiki policy before you start editing.

Create a User Account

To edit the Joomla! Documentation Wiki, you will need a user account. You may register for one here. After confirming your email address you will have immediate permission to edit any page except for a few that are protected.

Create a User Page

After you have created an account, confirmed your email address and logged in, you should create a user page. A quick cheat to start your user page:
  • actions drop down
  • create
  • add the code to editor{{subst:Newuser}}
  • fill in summary (e.g. my new user page)
  • save

Join the Documentation Mail List

You should join the Docs mail list. It is not required but there are discussions you will miss out on which are relevant to documentation.

What Should I Do First?

There are several areas of documentation which always need attention. You can start by picking the one which is the most comfortable for you to work on or you may get more involved by working on several at a time. Once you have a wiki account, you are free to work on any aspect of the documentation that takes your fancy. Even the simplest contributions such as spelling corrections and grammar fixes are a tremendous help!

  1. Help with documentation content.
  2. Maintenance Tasks.
  3. Join or start documentation project.
  4. Help with Help Screens.

Help Manage Our Content

  1. Editing, rewriting and reorganising pages. Check our Needs pages for areas needing immediate help. They are called 'Needs pages' because they are in need of small tasks to complete them. Some of them are as simple as reviewing content or adding an image. Others require more content or improvements. Pick a few, give them a little love. This is a tremendous help to Joomla! users who rely on our documentation.
  2. Have some fun and browse for articles which are redundant, out of version(i.e. 1.0 and 1.5), or need to be split up because of version specific information. Then feel free to make use of the {{delete}}, {{merge}} or {{JSplit}} templates on the articles. Click the previous template links to see how to use and apply them to articles you think need these marker templates. Add them to the very top of a page and the page is marked.
  3. Create a new page or tutorial. If you want to start a new page, do some extensive research first. Try not to create a new article if one already exists. Use the search feature of the Docs Wiki to see if your topic is already in an article. Duplication will be merged and/or deleted. Don't be afraid to modify, reformat or improve someone else's work on the Joomla! Docs Wiki! This is a collaborative documentation wiki, just make sure you are following our policy and guidelines.

Wiki Maintenance

Maintaining a wiki and keeping it organised takes a lot of continuous work on the part of administrators, editors and users. There are always tasks needing attention such as: Categorisation, attending to pages with needs or marking pages for deletion, merging or splitting. For all maintenance tasks and ideas of how you can help, please visit our Documentation Maintenance page.

Documentation Projects

  • The docs team is working on Beginner Tutorials. Our goal is to make them easy to understand and navigate, something a Beginner can follow easily and learn basic concepts. Think back to when you were new to Joomla! and add a topic about something you struggled with as a beginner to the page. Better yet, join the Beginner Tutorials Project.
  • Join the Developer Tutorials Project and share your knowledge. Sign your name using 4 tildes ( ~~~~ ) on the Developer Tutorials Project page and list what you might be able to do. Feel free to add some tutorial topics to the suggested topics list.

Help Screens

Unknown to many, all Help Screen pages are created and served to every Joomla! Installation worldwide from this wiki! They are necessary for beginners and even those with intermediate knowledge of Joomla!

The Joomla! 2.5 Help Screens are complete but Joomla! 3.x are still being worked on! The contributions you give to them will be appreciated by many users worldwide. You can find the matrix of 3.x Help Screens here. Some just need to be reviewed and marked complete in status, others need to be started, completed, have images uploaded(670px max width), etc.

Things to Remember

Here a a few things to remember as a Joomla! Docs contributor.

  • Don't be afraid to break a page, if you do and something has gone really wrong, revert your edit. Click the page's View History tab and you will see links to undo and revert.
  • Write articles with a sense they will translated to another language. Using slang or local dialect may not translate to another language or its inferences be understood.
  • Don't be afraid to download and read the general Editorial Style Guide (PDF) that applies to all Joomla! Documentation. There are helpful hints on how to write for Joomla! Documentation.
  • Words to watch when writing, read the full guideline … or for instant feedback use Google Chrome or Mozilla Firefow browsers. They both have built-in spell checking which underlines a misspelled word.
  • Don't forget to add the {{inuse}} template to an article you are going to be working on for a long period of time, more than a minute. It helps to prevent editing conflicts.

Help, I don't know Wiki Markup!

If you are new to the use of Wikis and the simple markup to create pages, then you can use the following for help.

  • New WikiEditor contains buttons and quick links to make building pages easier. Click the word 'Advanced' for a drop down of more buttons and quick formatting links.
  • Use the JDOC's Wiki Cheatsheet to learn the basic syntax commands. There is also a drop down of the common markup in the editor. Just click the word 'Help' once and it will appear.
  • Still afraid? Try these tools to help you create great wiki pages.
  • Microsoft Word Add-on for Wiki Markup, save Word Docs in Wiki Markup.
  • OpenOffice.org versions 2.4 and later have a MediaWiki export filter built in. Just open a Writer document and click File - Export. Then, change File format to MediaWiki.
  • Here is a list of tools available to convert other formats to wiki markup, e.g. HTML, Excel, CSV. Some of them are online converters, cut and paste HTML for an output in wiki markup.