The Future of Joomla! Documentation

[Jon Neubauer]

Good evening folks,

Over the last week, I had a short email exchange with Chris Davenport regarding ideas that we had brainstormed for the future of the Joomla! Documentation site.  Chris encouraged me to post them here, and get community input.  My initial email is immediately below, and I'll paste Chris's response in the next post to be followed by a response:

One of the most common complaints we see in the forums and in talking to new users is the lack of clear, and easily accessable and understandable documentation.  I know we (those of us that use Joomla! all the time and contribute to the docs) can easily pull up just about anything and say “Ha! there it is!” - unfortunately that skill doesn’t seem to carry down to everyone.

The other thing we’re starting to notice, and this is something I cautioned over a year ago, is the pitfalls of trying to support three versions of Joomla! and it’s documentation simultaneously on a wiki organized as it currently is.

A couple weeks ago we had a lengthy discussion in the Joomla! Launch Team chat about the state of the docs site, and ideas of how we can improve it.  Here’s what we came up with as a potential shift for the Joomla! docs site in light of the new development cycle, and to best serve Joomla!’s users.

I. Migrate to Joomla!

Joomla! (I believe) is the most powerful CMS in the world!  Ok, I might be a little bit biased, but I don’t think I’m too far off :).  So why can’t it handle a documentation site?  There’s no reason why not.  I’ve personally built very large documentation sites, and collaborative ones at that.  One of our most recent project involved building an entire Encyclopedia for the United Nations inside of Joomla! - and a collaborative one at that.  This is going to require some major shifts in how content is handled though.  We’ve given this a lot of thought, so I’ve listed out the major changes that will need to take place, as well as some workflow changes that can be implemented.

Utilizing Joomla! can actually bring us a lot of benefits:

• No more questions on how to format things in a wiki, using editor standards like JCE or others, contributors will be interacting with the same interface they are familiar with.
• Easily organize the site to support multiple languages - offering documentation for other languages is a big step in bringing together the international community
• Easily organize and support documentation for sequential versions of the Joomla! software, and archive older versions as well
• The use of Smart Search to help users find the content they need faster

We could create lists hundreds of items long on the benefits of using Joomla! for the Joomla! Documentation, but those three are probably the top items that brnig the most benefit to everyone.

This will require a significant amount of work to migrate the existing documentation over.  One idea that has been proposed is, since we are coming up on a new version series with 3.0, to simply leave the existing docs site as an archive, and start from scratch with new or updated documentation for 3.0 - with the changes that I see already being worked on for 3.0, that might be closer to reality no matter which way we go here :)

II. Organize the Documentation team, and Encourage New Contributors

One of the biggest changes that would have to happen is a new, or re-organization of the Documentation team, and how contributions work.  Obviously, moving away from the wiki format changes the way content updates are handled.  But I think this can be an opportunity, rather than a roadblock.
The first change is versioning.  Since Joomla! core content currently doesn’t support native versioning of content, we’ll have to get a bit creative here.  Whether it’s utilizing something like Flexicontent that does versioning nicely, or eventually adopting the proposed UCM to give us greater flexibility, I think this challenge is one that can be overcome.  Obviously this needs great consideration though.
The second change is the way documentation contributions are handled.  In talking with others in the community, one of the suggestions that came out that I really liked (actually came from Paul Orwig) is similar to the structure we currently have in the JCM.  A system where a “Documentation Team” reviews contributions to make sure they are correct, and make sure they are the most beneficial to users, yest still encourages all Joomla! users to offer contributions.  As a JCM editor myself, I can attest to the success of a system like this, and the benefits it can bring to a project like the documentation site.


Following these discussions, and with the input of several others, I put up a site to try to sort out how everything would work together.  You can see it here http://jdocs.jonneubauer.com/
That site is really just a couple pages, but it demonstrates the potential for organizing the documentation site in a better manner, and supporting new features, like multiple languages.  There’s only one link from the home page, it’s the Beginners Guide under the Joomla! 2.5 section.  If you follow it, you’ll notice the organization clearly displayed in the url path - easy to follow, and organized. 

[Jon Neubauer]

Chris's Response:

Hi Jon,

Thank you for putting together your proposal.  Constructive criticism is always much appreciated.

As your idea of moving the documentation to Joomla is a complete reversal of the decision, made some years ago, to move the documentation off Joomla and onto MediaWiki, I think it is useful to re-examine the reasoning behind that earlier decision to see if it still applies.

At the time we had two documentation sites.  User documentation was hosted at help.joomla.org and worked reasonably well for some aspects of the documentation at the time.  However, we were running into various problems that suggested that a new approach was needed and that a wiki would be more appropriate.  Meanwhile, developer documentation was hosted at the old developer.joomla.org site in a wiki component, which if I recall correctly was a re-packaged version of DocuWiki.  Again, this worked well in some areas but it was not a richly-featured wiki and we were encountering issues that were not easy to solve.

To summarise the issues that we were facing:

• it was hard to get people to contribute.   We had a formal Documentation Team and despite anyone being welcome to join, it was hard to persuade people to make the commitment to do so.  People actually don't like joining teams because it requires commitment.  Okay, that's too much of a generalisation since obviously some people are happy to commit to joining a team and making lots of contributions, but they are comparatively rare individuals.
• it was difficult to get a consistent style across the site as different people were using different conventions and the WYSIWYG editor had a tendency to break the markup frequently.
• we were wasting a lot of time repeating blocks of text and then having the headache of having to remember where each block had been used when an amendment to one required that the others be updated too.
• Joomla, at the time (version 1.0), had a number of technical limitations which meant that it was not an ideal platform for hosting the documentation:-
• No version control.  If someone made a bad edit it was impossible to recover the earlier version.
• No transclusion support, which would have gone a long way to solving the repeating blocks of text issue mentioned above.
• Importing documents from other sources was not simple.
• Exporting pages or groups of pages was also not simple.  It was difficult to get documentation out of Joomla in any format other than HTML and converting from HTML to other formats was not trivial.
• No web API to allow integration with other applications
• Multi-language support was crude at best
• Some of the documentation at the time was written in DocBook, but there were no WYSIWYG editors available for DocBook and contributors were finding it hard to maintain because they were not comfortable editing XML files directly.
  

So, in looking at how we could go forward with the documentation, we had a number of goals in mind:

• Lower barriers to contribution.  It was clear that a small team of perhaps half a dozen or so active volunteers would be unable to make much headway and we needed to find a way to unlock the potential of hundreds or even thousands of contributors, even though most would be making only relatively small edits.
• Move towards a single-source, modular documentation model.  To maximise the effectiveness of volunteers, eliminate duplication of effort and bring about a more consistent style and structure to the documentation, we wanted to be able to write documentation in small, context-free, re-usable "chunks" and then be able to assemble finished documents from these re-usable chunks with the minimum of connecting text.
• Make it easier to generate finished documents in multiple output formats.
• Version control is critical.
• Multi-language support that would enable the translation teams to host their own documentation sites containing translated versions of the official English-language documentation as well as local additions.
• Reduce the administration involved  in managing volunteer access to the documentation sources.
  

Now, like you, I was reluctant to move away from Joomla but it wasn't until we took a close look at MediaWiki that we realised what we'd been missing!

• The wiki methodology is ideally suited to loose, informal contributions.
• MediaWiki has native support for "transclusion" right out-of-the-box, which gave us the tools needed to construct modular documentation.
• Version control built-in, together with a host of other features for managing edits, such as:
• revert and rollback of edits is easy.
• patrolled edits make it easier to spot spam and remove it quickly.
• automatic email notifications make 24/7 monitoring less of an effort.
• protected pages make it possible to restrict edit access to high profile pages that tend to attract the most attention from spammers.
• Support for interwiki multi-language so that language wikis could be set up in separate domains or sub-domains with interconnections being maintained with the aid of a simple script.
• Tools for user management:
• User groups with configurable access levels.
• Spam control features.
• A complete web API that allows not only import and export of data, but almost complete management of the wiki from external applications.
• Bulk import of wiki data, which is something we have used on more than one occasion.
• Bulk export of wiki data to allow integration with publishing tool-chains.
• Tagging (called "categories" in MediaWiki).
  

Okay, so that brings us up to the present day where we have what I think has been a very successful wiki-based documentation site.  Which, of course, is not to say that there isn't considerable room for improvement, so let's look at the problems we now face.

• the documentation lacks structure.  This is probably the biggest downside of using a wiki.  Most edits occur on a small scale without regard to the "big picture" and over time this leads to the lack of systematic structure that we see today.
• there is a need to re-organise the content so as to better support multiple simultaneous Joomla versions, the accelerated release of new versions and the limited lifespan of short-term support releases.
• we still haven't achieved our goal of producing documents in multiple formats even though the tools exist to do it.
• we still haven't made any real progress on setting up multiple language versions of the documentation.
  

So, turning now to a consideration of your proposal, as I see it there are two distinct aspects to what you are saying.  Firstly, the proposal to move from the wiki back to Joomla and secondly to have a more formal team structure to control the documentation by providing editorial oversight.

Whilst it would certainly be possible in theory to move back to Joomla, we would first need to develop code to support the features that attracted us to move to MediaWiki in the first place.  In particular,

• Versioning is absolutely essential, not just for document management, but also for licensing.  I don't think we would even consider moving to a platform that did not allow us to view and compare prior versions and to revert and/or rollback to a prior version easily as required.
• Transclusion.  At a basic level this could be done with just a simple content plug-in.  Most of the time we don't need the sophistication of MediaWiki's parser.  However, I think that some form of transclusion support is essential.
• Wiki templates (not to be confused with Joomla templates, which serve a completely different purpose).  On the documentation wiki we make extensive use of templates and we would need to develop equivalent functionality to replace them.
• Tagging.
  

In addition, we would also need to develop some means of migrating the content.  That's a tough one if the aim is to not lose anything in the process.

I think that the Joomla 2.5 user management and ACL is now at least as good as MediaWiki's so that should no longer present a problem.  We could develop code to support a web API and import/export as required on a case-by-case basis.  Probably a bit more work, but it's not something we do every day and we usually need to write custom code for MediaWiki anyway, so not much change there.

Multi-language is an interesting one.  Although Joomla is now much more capable of handling multi-lingual content than it was before we moved to the wiki, I still have some concerns about how it would work in practice on a Joomla site.  There are, I think, three approaches that could be used:

• use the multilang feature in Joomla 2.5+.  However, there is no 1-to-1 correspondence between pages in one language and the same page in another language.  Separate navigation structures would need to be maintained.
• use JoomFish when it becomes available for Joomla 2.5+.  The JoomFish interface is complex and is not easy for novice users (unless they've changed it significantly for the Joomla 2.5 version).  It also requires back-end access for content editing (again, unless they've changed it).
• use separate sites in separate sub-domains for each language.  Again, the problem is that there is no 1-to-1 correspondence between different language versions of the same material (but see below).
  

Now, the current plan for multi-language Joomla documentation is to set up separate MediaWiki installations in language-specific sub-domains and use the already existing support within MediaWiki to connect corresponding pages between the sites.  This was started on an experimental basis for Danish but lack of time eventually forced its abandonment.  I have a couple of people who have expressed an interest in helping out with setting up language wikis, but I haven't been able to devote the time to moving this forward recently.

One possibility that would be worth investigating is to use a similar technique to that used by MediaWiki to link corresponding articles across sub-domains running Joomla.  Needs some thought, but I don't see why it could not be done.  The main point though, is that multi-language is hard and whatever way is chosen it will require a lot of time to implement.

You are correct in that we did not really take multiple Joomla versions into account when we moved to the wiki.  Indeed, much of the documentation for 1.0 has never been transferred from help.joomla.org, although this was mainly due to licensing restrictions rather than anything technical.  However, I am of the opinion that there is nothing stopping us from supporting multiple versions in the wiki given an appropriate strategy for doing so.

The second aspect of your proposal is to form a more formal documentation team that would provide editorial control over submissions.  It's true that the documentation would benefit hugely from having an editorial team or teams looking after and creating documentation in some areas.  For example, the creation of an Administrators Manual or even a Developers Manual.  However, this is true no matter what medium is chosen for hosting the documentation, whether it be Joomla or MediaWiki.  It just needs people who are willing and able to make the commitment necessary to do it and they are really hard to find.  I have absolutely no objection to people wanting to take responsibility for one or more areas of the documentation and providing editorial oversight over all contributions in those areas.  If you're volunteering to take that on, then welcome aboard!

Taking your proposal as stated I would respond by saying that Joomla is not yet able to satisfy our requirements.  Of course, that could be changed but it would require significant development time.  Probably the first step would be write a specification for exactly what would be required and how it could be developed within Joomla, then see if anyone is available to write the code.

However, there is an alternative approach that does not require the abandonment of the wiki and does not require significant development time and that is to re-use the wiki content in a Joomla website by pulling it via the wiki API.  This is already being done with the help screens proxy server and it would be straightforward enough to write a simple content plug-in to pull pages directly from the wiki into a Joomla content item (article or category, say).  I have a partially-developed MediaWiki library that could help with that.

So here is my proposal to you.  Form an editorial team that will construct a Joomla site, possibly aimed specifically at Joomla 3.x, that will pull most of its content from the documentation wiki.  Choose an initial topic area that you want to cover, let's say the Administrators Manual for the sake of argument.  Build the structure for the finished product in Joomla then look for suitable raw material in the wiki to flesh out that structure.  If you find something suitable pull it in using a content plug-in.  If not then write it and either add it to the wiki or include it in your Joomla article, with preference given to using the wiki so that the content can be re-used elsewhere.

Retaining the wiki gives you a pool of raw material from which to draw the nuggets that your editors can then assemble into a more polished product.  In effect, the Joomla site becomes a downstream user of the wiki content.  Editorial "fixes" can be pushed upstream as required.

This approach has a number of advantages:

• it retains the numerous positive advantages of using a wiki, particularly when it comes to casual contributions and the need to keep the barriers to contribution as low as possible.
• it doesn't require the development of substantial new features in Joomla to replicate functionality that we already have in the wiki.
• it doesn't require the massive effort that would be needed to migrate existing content to a new platform.
• it promotes an experimental approach where different ways of assembling the documentation can be tried and those that work can be retained.
• it promotes the single-source, modular approach to documentation that is something I and others have been preaching for many years.
• it should have beneficial effects on the wiki structure as changes that are shown to work in the Joomla-based documentation can be fed upstream to the wiki.
• as content is adjusted for use by a downstream user it should become less context-sensitive and that will make it easier to re-use in other contexts.
  

Incidentally, our vision for the long-term future of help.joomla.org is that it become a true point of entry for getting help with all aspects of Joomla.  A key component of that would be a domain-wide search capability, possibly based on Smart Search, although given the scale, more likely based on a standalone search engine with Solr being the prime candidate.  This would clearly require a great deal of work which is currently outside of our capabilities, but it is a goal that is worth keeping in mind.

So, in conclusion, I would not recommend abandonment of the wiki but would instead suggest a hybrid approach that retains the best of both worlds as much as possible.  A Documentation Team reviewing contributions would be brilliant, but that does not depend on the underlying platform that is hosting the documentation.  The problem is not the medium or the tools; the problem is getting enough people with the skills and the time to write the documentation.  But then that's always been the major issue.

Finally, I don't see any reason for this discussion to be held in private and I would urge you to move your original document and this response onto a public mailing list; either joomla-docs or possibly the joomla-general list.  Others are very likely to have useful input on what is being discussed and given my limited availability you will almost certainly get faster responses to your enquiries.  I look forward to further discussions and ideas about moving the documentation effort forward.

All the best,
Chris. 

[Jon Neubauer]

That's a big response :)  Thanks Chris for taking the time to spell that all out!

First, thanks for the information regarding the history of the J!Docs - greatly appreciated helping show how we got to this place.

Regarding the use of a wiki software to house the Joomla! Documentation:

First, I'm no stranger to wikis, as an administrator for Wikipedia, I sort through, create, fix, move, moderate, remove, flag, and correct thousands of articles every week on the same software we use for J!Docs.

While I'd agree that wikis bring a lower barrier of entry, I think that is over-exaggerated.  What I hear at least once a week in various chats and email threads goes something like this: "Hey Guys, I (some contributor) have a page I'd like to add to the documentation site, can someone help me get it in there and format it?  I have no clue how to format/create/categorize content".  As often as possible I am more than happy to assist those people, but I say that to demonstrate that just because a user has the permission to do something, doesn't mean they can.

Regarding transclusion - while it is a handy tool, in my work in the Joomla! Documentation, transclusion is more a hindrance than a help.  In fact, the thread previous to this one is a user running into this problem.  Someone creates a "chunk" (reusable content, transclusion), we update versions, all of the sudden one of two things happen. 1) the new documentation is wrong, someone has to first scratch their head until they realize it is a chunk, then delete the use of that chunk in the article, and write the content in, or, and this is what I see happening most, 2) someone, after scratching their head and realizing it is a chunk, goes and edits the chunk to update it, thus making all other uses of that chunk for previous documentation documents invalid.  Either way, this is not a good thing.  Wikipedia has largely discouraged the use of chunks/transclusion for everything except administrative/notice templates for this very reason, it causes much more confusion than the short amount of time it actually saves.  In the documentation site we have "chunks" - reusable content that is supposed to be context free so that it can be used in multiple areas.  However, with different versions coming in that has ceased to be the case.  While someone might edit a chunk to update it for 1.6, they just broke all uses of that chunk for 1.5.  While some might say, "Well, they should just clone that chunk then, that's the right thing to do!"  Unfortunately, that doesn't happen, and unless you want to require every contributor to go through a 5 hour course on wiki management (I have :) ) then you'll never get that to happen.

Version control is easily the best feature a wiki brings to the game,and it does so beautifully.  However, with the upcoming implementation of UCM, I see an opportunity to have all these features inside of Joomla!, instead of using a separate software.

Multi-lingual features are nice, and that can also be done nicely in mediawiki.  BUT... it hasn't.  So we can't rest on the laurels of we could do, but haven't done.  Joomla! also has beautiful multi-language support now, so the weight that this holds in a decision to use the wiki is virtually none.  I myself have done several multi-language sites in Joomla!.  One that we're getting ready to release in 2.5 for the United Nations supports 13 languages beautifully.

Back to the problems:

One of the biggest problems we see in the wiki is the complete lack of organization.  So many times I hear people say that they are going to "throw something up on the docs site".  And I cringe, because that's one more article that will not be categorized properly, and will be virtually inaccessible to users save for a direct link.  With multiple versions coming into play here, that annoyance just descended into chaos, and the thought of then throwing multiple languages on top of that makes me shudder.

I do think that using Joomla! provides enormous benefits for organization and presentation of content.  Not to mention the ease of use for contributors.

Regarding the formation of editorial teams to oversee documentation:

I do think that whichever direction we head, this would be immensely helpful in keeping our documentation organized.

And yes, I am volunteering for this :)  I'd like to have a discussion at some point on how the teams should be organized, but definitely, I would be more than happy to assist here!

Regarding using a duplicate site:

For an area of the project that already has problems getting volunteers to maintain one site, I can't see how creating two sites that must be updated will help :(

To Recap:

After everything is considered, I still maintain that it would be in our best interest to use a platform that we are not only more knowledgeable in, but also one that has more than enough potential to manage the growth of the CMS (and the Platform for that matter) across several languages and versions.

I do see the difficulties in migrating.  Again, because of the use of chunks, that task just got harder.  At this point though, we are coming up on a 3.x release that will be so different it may be worth it to simply start from scratch!

Finally, I'd like to encourage everyone to chime in with thoughts and ideas!  Whatever we decide here, I am confident that it will mean progress for the documentation site, and I'm excited about that :).  I initially started working in the documentation a couple years ago, but the improbability of making any clear progress quickly became apparent.  Hopefully though we can put our heads together and put out a documentation site that will benefit all Joomla! users!

[Mark Dexter]

I have the following thoughts about this.

1. I worry that the implementing the proposal would take a huge amount of effort. I would rather see that effort go into adding and updating documentation within our existing structure.

2. I think we could get an improved organization simply by taking better advantage of the Wiki categories.

3. I think the Wiki encourages community involvement in adding documentation as much or more than having it run inside a Joomla site.

4. I think we could easily improve the search on the wiki simply by using Google. I (and many others) always use Google to search it now ("site:docs.joomla.org my search").

5. I'm not sure what to say about multi-language. I would strongly guess that the limiting factor for this is the availability of person-hours, not the format of the site. It is difficult enough to keep up with docs in English, where we have the benefit of a large number of native and non-native speakers. How much more difficult is it with a much smaller community of volunteers to draw from?

6. I think it is great to try to improve the access to the docs information, especially from the point of view of newcomers to Joomla. If we could develop some concrete suggestions to make this easier -- independent of the docs platform -- then I think we could explore how to do this within the existing Wiki.

My .02. Mark

--
You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/grbn3xzmNYkJ.

To post to this group, send email to jooml...@googlegroups.com.
To unsubscribe from this group, send email to joomla-docs...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/joomla-docs?hl=en.

--
You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/t43JDRoXkooJ.

To post to this group, send email to jooml...@googlegroups.com.
To unsubscribe from this group, send email to joomla-docs...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/joomla-docs?hl=en.

[Jon Neubauer]

Regarding the management of content itself, I agree.  Hopefully this discussion will result in ideas and actionable items that we can tackle to improve users documentation experience regardless of the platform.

However, I still reiterate that just trying to use categories to provide better categorization is just a band-aid on a problem.  The truth is, that with the potential for multiple languages, compounded with up to three versions of software, the loose structure of wiki categories just doesn't cut it in my experience.

Regarding the amount of effort - I have no doubt that this will be an enormous effort, and I'm willing to dedicate a large amount of time myself to make this happen.  I think we are actually helped by the fact that in the upcoming major release we will be rewriting a lot of content anyways.

[Webdongle]

• The problem with the wiki is that there are several pages on each subject and all of them say something different.
• The ACL of Joomla and the ability to limit editing to specific categories far excels that of  the wiki
• The documentation needs to be more organised (no a criticism on anyone's effort) because the documentation has out grown the limitations of the wiki
• Everyone and his dog can contribute is a downside not a benefit, why encourage that ?  Is it in the hopes that others will contribute to the wiki instead of creating their own documentation ?
• The documentation should be the same as the documentation that is seen when the 'Help' is clicked within Joomla instead of being a menagerie of differing opinions like in the wiki now.

+1 for Jon Neubauer's suggestion.

[Jon Neubauer]

Thanks @Webdongle.

To clarify, the suggested overhaul is not a reflection on the folks that spent countless hours building the documentation.  The wiki was envisioned, and put in place in a time when the thought of trying to support multiple versions at the same time was not even a consideration.  If anything, this is just a reflection on the fact that we've 1) outgrown the current capabilities of the wiki, and 2) the Joomla! CMS has grown immensely, and is almost to a point where it can handle everything the wiki can, but better :)

[Noel Dixon (Noxidsoft)]

Hi people,

At the moment, honestly I am a little intimidated to put my hand in the jar.

I just followed the link(s) from here, "Helping with the documentation effort":
http://docs.joomla.org/Main_Page

...and noticed that we are still referring to the 1.6 genre (thought we were on 2.5.x LTS?), anyhow. On clicking the "Joomla! Help screens project" I see all versions and assume...

• Joomla! 2.5 help screens

...is the way to go, to (choc) chip in. Now everything is pretty much "Not started", wooten, I can pick anything I like. Boohoo, then it's discovered that everything is already written (I already knew this, cause I use 2.5.x extensively, including user end help screens).

Can someone please clue me in on what is happening, save a poor idiot, I know I don't read every instance of this group, time constraints like everyone else, but nothing is obvious anymore? No the styleguide doesn't help.

Kind regards,
Noel (Noxidsoft)

[Chris Davenport]

Hi Noel,

This should really be in a separate thread, but...

If you study the help screens a little more closely you will see that almost all of them still require work.  When 2.5 was released they were simply copy-pasted from the 1.7 help screens and the links fixed up.  This means at the very least that almost all images need to be checked and updated.  I'm sure there are new fields and even entire features that were added in 2.5 (and in some cases in 1.7) that are missing from the help screens.  A careful, side-by-side comparison of each Joomla screen and its corresponding help screen will reveal a lot of work that should be done.

Over and above the mere "description of what is there", I'd also like to see links to more task-orientated pages.  For example, someone faced with the task of getting a menu item to point to an article might click on the help button in the Article Manager, where they'd be struggling to find the answer.  We need pages that describe how to perform common tasks and then add links to those pages from the appropriate help screens.

That should be plenty to get you started. ;-)

Chris.

--
You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/oDamSq6ZUmQJ.

To post to this group, send email to jooml...@googlegroups.com.
To unsubscribe from this group, send email to joomla-docs...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/joomla-docs?hl=en.

--
Chris Davenport
Joomla Leadership Team - Production Working Group
Joomla Documentation Coordinator

[Noel Dixon (Noxidsoft)]

Thank you for the response Chris,

Understood, good to have some leadership on where to begin.

I am shocked no one has broken the ice yet then? But, it is almost like being the first person to eyeball the arctic, will I be first to step out on terra firma :)

...I'll crack in on images then, to start with.

Kind regards,
Noel (Noxidsoft)

On Tuesday, March 20, 2012 5:51:35 PM UTC+10, Chris Davenport wrote:

Hi Noel,

This should really be in a separate thread, but...

If you study the help screens a little more closely you will see that almost all of them still require work.  When 2.5 was released they were simply copy-pasted from the 1.7 help screens and the links fixed up.  This means at the very least that almost all images need to be checked and updated.  I'm sure there are new fields and even entire features that were added in 2.5 (and in some cases in 1.7) that are missing from the help screens.  A careful, side-by-side comparison of each Joomla screen and its corresponding help screen will reveal a lot of work that should be done.

Over and above the mere "description of what is there", I'd also like to see links to more task-orientated pages.  For example, someone faced with the task of getting a menu item to point to an article might click on the help button in the Article Manager, where they'd be struggling to find the answer.  We need pages that describe how to perform common tasks and then add links to those pages from the appropriate help screens.

That should be plenty to get you started. ;-)

Chris.

On 20 March 2012 06:29, Noel Dixon (Noxidsoft) <removed> wrote:

Hi people,

At the moment, honestly I am a little intimidated to put my hand in the jar.

I just followed the link(s) from here, "Helping with the documentation effort":
http://docs.joomla.org/Main_Page

...and noticed that we are still referring to the 1.6 genre (thought we were on 2.5.x LTS?), anyhow. On clicking the "Joomla! Help screens project" I see all versions and assume...

• Joomla! 2.5 help screens

...is the way to go, to (choc) chip in. Now everything is pretty much "Not started", wooten, I can pick anything I like. Boohoo, then it's discovered that everything is already written (I already knew this, cause I use 2.5.x extensively, including user end help screens).

Can someone please clue me in on what is happening, save a poor idiot, I know I don't read every instance of this group, time constraints like everyone else, but nothing is obvious anymore? No the styleguide doesn't help.

Kind regards,
Noel (Noxidsoft)

--
You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/oDamSq6ZUmQJ.

To post to this group, send email to jooml...@googlegroups.com.

To unsubscribe from this group, send email to joomla-docs+unsubscribe@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/joomla-docs?hl=en.

[Chris Davenport]

Thank you.

Chris.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/Efz6U5HQYg8J.

To post to this group, send email to jooml...@googlegroups.com.

To unsubscribe from this group, send email to joomla-docs...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/joomla-docs?hl=en.

[Jonathan Neubauer]

to get back to the original point of this discussion:

I'd appreciate continued thoughts and ideas on redoing the documentation site.

I think this is very important.

I was talking with a Joomla! user today who said that they've all but given up on the documentation site, it's practically useless to them.

[Mark Dexter]

But who is to say that we won't get exactly the same comment no matter what format we put the documentation? People always complain about documentation and say it's useless.

I think are #1 problem is lack of person-hours working on documentation. So I think spending a lot of time reorganizing it could be counterproductive. But that's just my .02.

Mark

--
You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/UtGOZUWHLr4J.

[Jonathan Neubauer]

Speaking of lack of person hours - I actually think the wiki drives people away.

A I referenced earlier, I can't tell you how many times I've heard people asking for assistance because they don't know how to enter or format content in a wiki.

If we really want to lower barriers for contribution, then we should be using a system we all know very well.

As far as complaints - seriously, how many people will complain that the Joomla! Project is using the Joomla! CMS for documentation?!? :)

[Jonathan Neubauer]

My primary focus is creating and presenting quality documentation in a logical, and usable manner.

I definitely don't want to hurt peoples feelings - but the wiki is not doing that.  And, if we want to support multiple languages, combine that with now having to support multiple versions of Joomla!, the wiki is not the most logical solution for us.

[Webdongle]

But if the docs were in a Joomla 2.5 site they would be easier to search.  And if only a few people could create the documentation (instead of everyone and their dog) it would be more organised.  And thus more relevant to users.  The fact that the wiki search is useless and people are creating pages wili nili is creating chaos.

To unsubscribe from this group, send email to joomla-docs+unsubscribe@googlegroups.com.

[Jonathan Neubauer]

good points Webdongle - the concept of  "throw it up on the wiki" doesn't make life any easier :)

[Tony Davis]

Is there any evidence of what constitutes good practice for documentation?

Coming from a health background I was aware of http://bit.ly/GGY49a which is a pdf.

And very similar ideas presented from a technical background here

http://forrest.apache.org/howto-howto.html

I know which I prefer.

I do not know all their names but, for example, could Jen Kramer be invited to offer advice on how beginners and intermediates are most effectively introduced to the concepts and practices of Joomla! ?

From a long time lurker

who is intimidated by wiki management

Tony Davis 

[Noel Dixon]

While you folks work that out, I'll keep writing docs.

Kind regards, 

Noel Dixon

www.noxidsoft.com

Sent from my iPhone

[Jonathan Neubauer]

Noel,

This conversation is primarily happening between people who have spent hundreds, if not thousands of hours working for the Joomla! Project.

While I definitely appreciate the work that everyone does, this is definitely an important discussion regardless of the outcome.

Without changes to some degree, the Joomla! documentation site will continue to be something thats hard to use, and hard to manage, no matter how many times people update documentation.

So please, let us "work that out"

Respectfully,

Jon

[Chad Windnagle]

Hi everyone:

So just a little background on myself before I comment, I used to be on the docs team back in 2008 - 2009. I retired from the team to take on some other aspects of the Joomla project.

I can definitely appreciate the time and energy spent in creating and working on the docs site. having created many of the docs as a part of the GHOP program I know that the folks who have been working on the docs site, considering the task they are left with, they have done a great job thus far. 

Recently someone said to me that no one should control ideas. And I'm not insinuating that anyone is or has here, but I think that it's a good reminder to remember that we're all trying to do the best for the community and for the lesser joomla-head power users.

Jon has done a lot of work on this and I think we can definitely respect and thank him for that. His ideas are great ideas and they take on a lot of the issues that the docs site is currently struggling with. I can understand the need for some of the features that Chris mentioned, such as versioning and transclusion, but it's important to not let the need for certain things like that get in the way of meeting a larger goal: making the content usable.

With the Wiki we may have some great features like the versioning and transclusion, but what good is it if the docs site is rendered nearly useless in the process? It seems to me that we may be stepping over a dollar to save a nickel there, and I don't know if that tradeoff is worthwhile.

All in all, it's important to at least stay open to making some changes, and accept that there are other solutions out there. 

Cheers,

Chad

[Chris Davenport]

Hi Jon,

I'm more than happy for people to experiment with new ideas (or even old ones), so please don't let my scepticism stand in your way.  By all means give it a try.  If it works, that's great; if it doesn't then we can simply try something else.  In the meantime, the wiki will still be there and it will still be open for anyone interested in improving our current documentation.

I will simply state that in my opinion the effort that you are planning to expend on building something in Joomla could just as easily and more productively be used re-organising and building on what we already have.  We're not short of tools; what we are short of is time, skill and attention.  Switching tools is not going to change that, even if you can overcome the issues that I've highlighted.

But I'll be delighted if you can prove me wrong and I'll be the first to congratulate you if you can pull it off.

Let me know if you need anything from me.

Chris.

--

You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/C0bS3z9V4CwJ.

To post to this group, send email to jooml...@googlegroups.com.
To unsubscribe from this group, send email to joomla-docs...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/joomla-docs?hl=en.

--

[Noel Dixon]

Jon,

Up front my apologies if I offended you. Everyone's time is appreciated, let me rephrase.

I am glad others are sorting out the hard parts of where to go with the document delivery from now, so while you guys do that, I am going to keep writing and adding/updating images in the Help25 space so you can sort that out.

There was no hidden intent or meaning behind the comment.

Chin up people, your doing good work.

Kind regards,

Noel Dixon

--
You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/XbiTMY9aTqoJ.

[Noel Dixon]

Jon,

Re, Joomla doco idea, there is a great, but very simple Wordpress like versioning tool here (Content versions):

http://extensions.joomla.org/search?q=versions

Or something else might be needed to take care of rollback facility?

Kind regards,

Noel Dixon

--
You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/UtGOZUWHLr4J.

[Jonathan Neubauer]

Thanks for the clarification Noel :)

Re: versioning - absolutely - I definitely think that versioning can be accomplished in Joomla! - We're also looking to the upcoming implementation of UCM and the potential that that can bring to maintaining the documentation.

If you visit the demo/dev site we've set up to demonstrate functionality, you'll see a site that is logically organized, easily navigated, that easily supports multiple languages, and multiple versions, and is easily searched and browsed.  That's combined with very nice styling options afforded by Joomla! - and we're working on implementing a collaborative translation solution from our friends and anything-digital that will make maintaining translated documents through community efforts very easy.

With that said, I think the only thing missing is transclusion.  It's my opinion - and I know it's the opinion of many, many others - that transclusion is actually a part of the problem, not a part of the solution.  And clinging to that as a reason to stay with a wiki is simply making things a lot harder.

[Noel Dixon]

Jon,

Maybe I am a bit of an optimist but couldn't a dev fashion a parser to accomplish this?

Or…

 I am currently thinking of a plugin that filters these textual snippets and decides if they exist etc and presents an editor as per normal pre-filled or not; thinking similarities with the current Joomla new/edit process? I think this is quite possible.

Just a thought.

Sorry, what is the link to the demo setup you are referring to?

Regards,

Noel Dixon

On 23/03/2012, at 12:43 PM, Jonathan Neubauer wrote:

transclusion

[Jonathan Neubauer]

You're right - I'm confident that we could have some manner for transclusion if we wanted to.  But again, I think it's part of the problem, not part of the solution.

Transclusion is supposed to make documentation modular, easy to reuse.

However, as we start supporting multiple versions, I think the amount of time transclusion saves is overshadowed by the amount of work it takes to clean up after.

1. for someone new to a specific document, it takes them more time to either totally rewrite, or go find and edit the transcluded portion of text in order to correct it.
2. there are relatively few areas in Joomla! that are exactly the same.  Take the items lists in the administrator control panel - while they might appear similar, there are many differences in the filters available, toolbar options, and batch processing options.  The same with the edit view for different types of content - similar interface, different options.  Now, especially as we start trying to do this across multiple versions, you can see how this quickly gets even more confusing, and is more time consuming to fix than the short amount of time it saved initially.

With that in mind, transclusion seems to be a process that works to our detriment.  Either it takes more time to fix, or, someone does go and update the transcluded document for a new version, and inadvertently messes up the documentation for previous versions.  Either scenario is not good, and the process ends up being more frustrating than the small amount of time initially saved.

I don't know if anyone here has worked in any great part for Wikipedia, another large wiki site that uses the same wiki software.  I'm an administrator for Wikipedia (bureaucrat for those familiar with wiki-speak).  Wikipedia actually discourages the regular use of transclusion (chunks) for this exact reason.  While pieces of documentation or content may appear to be similar, they are rarely exactly alike.

So, while yes we can do it - I don't think we should.

But again, if we wanted to, I'm sure we could devise a way to do that in Joomla! - which would leave us with all the functionality of the wiki, but with many more benefits.

We'd also have a platform with which we are much more familiar with, and much easier for us to support.  Which, speaking of, did you know that the Joomla! Documentation site is currently more than eight versions behind the latest stable release of the Mediawiki software?  For an organization that stresses keeping up to date with latest releases, that's not a very good track record :)

Thanks again for the comments and ideas - keep them coming!  I think together we can build something that will bring much greater value to Joomla! users who, currently, view the docs site as an abyss, not very helpful in actually learning about Joomla!

[Noel Dixon]

Understood and agree on each point.

Kind regards, 

Noel Dixon

www.noxidsoft.com

Sent from my iPhone

--

You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/TtxMvxgEpGUJ.

[Tony Davis]

Overnight it occurred to me that that is the wrong question.

There are two points to address.

• What is the effective method for explaining some point.

This may vary depending upon the conceptual complexity of the point, the skill set of the user and the user's language preference.

• What is the user's preferred form of presenting those points.

This may vary too. There is surely no good reason for the Joomla audience not to be divided between those who prefer one approach to the other.  Indeed this could link to the user's current skill level.

For a commercial client I always counsel - Test, Test, Test (in the sense of A/B testing) - shouldn't we do the same.

If only as an example of taking our own medicine.  Using Joomla.  Testing alternate approaches.

Obvious criticism - takes more work.

I am happy to volunteer to be part of a bridging team coordinating content between two approaches.

Best wishes

Tony D

PS :) I suppose this post is an example of that approach.

[Jonathan Neubauer]

Excellent points Tony - and important questions to ask!

In our line of work, we do a lot of Joomla! training - our work revolves largely around government clients and enterprise organizations.  From those experiences I've noticed to different paths to approaching training:

1. Thorough text-based documentation - this is thorough, step by step documentation, complete with screenshots, for how to complete individual tasks, or groups of tasks.
2. Engaging video documentation - while similar in scope to text-based documentation, this presents a visual aspect, walking users through the tasks in real-time, presenting every step required.

Both of those types of documentation have their merits, and both can be enormously effective.  Depending on the type of organization or people, we find that some people prefer video, while others prefer text-based.

I think text-based documentation should be our focus - it's something that is very effective, and requires less server resources as well as less loading time from the end user, and is virtually universal in being able to view.

However, with that said, video documentation is enormously effective, and should be something that we consider in the future.  Maybe not for the entire site, that's an enormous amount of work, and is impractical for many aspects, especially developer documentation.  But what about the Beginners Guide?  Wouldn't it be nice to have a more thorough beginners guide, complete with videos?  That would go a long way in enabling our users to easily get up to speed on Joomla!

Currently our company goes to great efforts to build our own Joomla! documentation for users.  I honestly look forward to the day when I can point them to docs.joomla.org/beginners and trust that they will be able to easily, and logically glean a wealth of information from it!

Thoughts?  Any other ideas for alternate approaches?  I've always thought it would be interesting to have interactive documentation - something like a Joomla! installation that, when you log in, is actively giving you a walkthrough and tips about everything - not just help screens, an active guide as you step through Joomla!.  Maybe that's a bit far-fetched, it would most likely take an enormous amount of effort.  But it's an idea! :)

[Noel Dixon]

Another thought on transclusion.

This ideology can be reached through using existing tools within J2.5.x perhaps. Der me, both the Create Article component link for front end and the Article button below the editor may suffice. The only downside is that this doesn't check for pre-existing duplicates. Everything else seems to be in place though.

Just a thought.

Kind regards,

Noel Dixon - Noxidsoft

--
You received this message because you are subscribed to the Google Groups "Joomla! Documentation" group.

To view this discussion on the web visit https://groups.google.com/d/msg/joomla-docs/-/T5XpAWaQRYsJ.