Are things going in the right direction?

Replies to This Discussion

Permalink Reply by Tony Davis on October 30, 2009 at 3:14am

I am feeling a bit guilty that pages have not been appearing. I shall try to explain why not.

On one level writing a wiki is easy. Create a page, edit it contents and write your text. Rather hard work for the whole Manual. It turns out there is another method. I shall begin at the bottom and work up.

What I have been calling factoids - text elements that will be repeated in different places - are called Chunks in wikispeak. Here is one. These get assembled into what look like lists with use instructions which are called Templates (not like Joomla thinks of Templates). Here is a template which derives its content from this page. This template is used extensively in this article.

My aim is to get folk to contribute factoids and images. They will then be assembled into Manual Pages.

The reasoning behind this approach is that it will allow
1. Greater flexibility as we pass through Beta
2. Improved ability to manage the Manual and Help pages
3. Simpler approach to translation

In the next 24 hours I hope to have some examples for you.

Permalink Reply by Amy Stephen on October 30, 2009 at 9:03am

The problem with writing using a very small scope (factoids and images) is that it breaks a writer's thoughts when documenting a process.

In my thinking, there are three basic phases:

1. To begin, organize a TOC that has roomy topics (like you have done.) Then writers can take a section and move through it in a linear fashion identifying the process, step by step. Click this menu item. Enter the name of the Article in this field. Press Apply to save your work and stay in the editor or Save to save your work and close the editor. etc. When writing, context matters and breaking those pieces down too much during the writing process makes it very difficult to document the process.

2. The second phase would be a technical Wiki phase. After the basic chapters have been written, it makes sense that people who know the Wiki intimately (yourself, and Chris, likely?) walk through the work and identify factoids - and create the Wiki "chunk" - replacing the text with that include piece whatever Wiki needs to have good re-usability, and organize the work.

3. The third phase is upkeep - as beta progresses and changes are made, and as 1.6 is released and minor releases impact the interface, updates can be made, either to the "chunk" or to the process text. By that time, it will be more clear to everyone how to do that since they will find those wiki elements when they go to update the document.

If we want to get writers to document the process, I would suggest we not expect them to be Wiki experts or to understand the technical aspects needed for reuse. Just make it easy for them to write by creating a Table of Contents - and letting them fully document a section. Making it clear that a second phase will occur where Wiki editors build in helpful reuse for maintainability and accuracy, but not to worry about that since a writer's focus should be on identifying process, not wiki constructs.

Wiki is awesome because people can participate and it's easy to communicate where help is needed. That's the piece we have to make sure is available for crowd sourcing this content. Wiki is also cool because a smaller group can build intelligence and reuse into content. That's the piece we should reserve for the custodians of the site. If we try to mix them, we will most certainly lose writers. We will wind up with the Wiki technicians having to also do the writing.

That was unnecessarily long. If I had time to write less, I would have. (Also, botched that saying.) I hope some of that makes sense. It's just my opinion, of course, it's not scientific. I feel very strongly that the benefit of the Wiki is low barriers - adding in the sophistication takes that away, I fear.

Permalink Reply by Tony Davis on October 30, 2009 at 10:20am

I am happy with that approach. Do you have a tool in mind?

Word processed pages would seem to be the most obvious. Do you agree?
For the moment I am happy with where I am at and there are two bits to it.

1. Playing with the wiki.
Very happy with cooperation from Chris but I do need to discuss the 'how to' with him a bit. Then it seems that running the wiki will be a kind of editorial job. Happy with that too.

2. Playing with the alpha.
Less happy with that not knowing if it will tumble round my ears. Is there somewhere where I can see what is continuing from 1.5 and what is changing for 1.6? Rather than playing with and documenting the alpha I would be much happier writing the continuing stuff and letting the more deeply immersed correct my errors.

How does that sound?

TD

Permalink Reply by Amy Stephen on October 30, 2009 at 10:28am

I think I'm lost, a bit.

Earlier, you shared this link to a Table of Contents for a Joomla! 1.6 User's Guide on the Wiki.

I assumed people would simply take one of those TOC entries, document that topic, right on the Wiki or using Word, Open Office, and someone else would paste it in and do the basic markup.

The key being that the Table of Contents serves as a task list of sorts, and everyone could look at it to understand what work remains, what is in progress, and what is complete. This would be true whether people were participating here or as part of the broader Joomla! community.

Does that make sense Tony? What do others think? Do people know how to join in? Are you okay with these directions? Is anyone confused? Or, does everyone understand where things are going?

Permalink Reply by Tony Davis on October 30, 2009 at 11:12am

I endorse that absolutely.

1. The existing wiki will be expanded to provide lots of pages to work on.
2. If anyone writes in Word, Open Office or whatever that is fine and I will do the markup
3. I will also post a wiki page advising how to use the existing documentation to assist writing any page into the wiki.

Permalink Reply by Amy Stephen on November 1, 2009 at 10:03am

I wanted to copy your comments here so that we keep everyone in the loop.

Amy, I am waiting for advice from Chris about how to glue everything together but here is a brief on the present view.

There turns out to be quite a lot of stuff already in the wiki which will contribute to the Manual.
1. Stuff specially written already e.g. ACL
2. Some testing stuff for the 1.6 Help System
3. What we have been up to.
4. The 70% of 1.6 which will be common with 1.5

The wiki has a curious structure. It depends upon this kind of factoid. They are assembled in these boiler plates which are called templates - confusingly.

Basing the Manual on factoids seems a good way to go to allow localisation. Chris is being asked about how to build factoid -> template -> wiki pages. When that is cracked we will be good to go.

What is the date planned for Beta?

My response:
Not sure about Beta, to be honest, maybe a month? Six weeks?

Glad you are getting into the details of how this all fits together and what is needed and not needed. We certainly don't want to waste time writing about topics already covered. If we can get to a specific set of items, then it's easier to get people involved.

I'm not certain where we should begin. Do you and Chris have ideas on that?