Documentation for Joomla! 1.6

[daverii]

The second alpha release is already in the wild. The first beta is expected shortly.

Amy Stephen has created a Ning site where this development is being discussed and one topic is the development of documentation for Joomla! 1.6

The first steps for that can be seen here.

Could you contribute? Would you like to? All help is gratefully received.

[daverii]

May I ask for Wiki help?

I am in the early stages of constructing a Manual for 1.6. See here.

I would like the wiki to be a support to the effort. To this end I am attempting to both use the in built functions to manage the navigation and have page names which make sense.

From the root of the Manual I think there may be 4 or 5 levels of hierarchy to some of the pages. This has two effects which may be judged undesirable.

• Long page names
• Complex lists generated by prefixindex

Is there an easy way round this dilemma?
Is there a way to suppress prefixindex output if the list is empty?
Is there a way of arbitrarily ordering a list produced by prefixindex for a sub directory or must something like numerical prefixed be used to achieve that end?

Thanks for the help.

[Chris Davenport]

Hi Tony,

Regarding long page names... These are, of course, a direct result of using sub-pages rather liberally. ;-)

The approach I would tend to take is create/define document modules that are written independently of the context in which they are placed. Each module (which is most likely going to equate to a single page in the wiki) will talk about a single idea/concept/task/procedure/whatever and will have a descriptive title. These modules will not be sub-pages of any other page.

Modules can then be assembled into complete documents, either by linking to them, or more likely by transcluding them into pages that define the context. These can be in a sub-page hierarchy and can also include linking text, headers, and cross-references which are context-dependent, but which together bind the context-independent modules together to form a coherent document.

So the module pages, which is where the vast bulk of the text and images are located, have relatively short names, whereas the long sub-page names are only used when assembling a document for a particular purpose or audience.

For example, suppose we have some modules, called Module 1, Module 2, and so on. Then we can assembly a document using a sub-page hierarchy like this:

Code: Select all

Document 1
+--Chapter 1
     +--"Some text introducing Chapter 1"
     +--{{Module 2}}
     +--"Some text linking Module 2 to Module 3"
     +--{{Module 3}}
     +--"Some final remarks about Chapter 1"
+--Chapter 2
     +--"Some text introducing Chapter 2"
     +--{{Module 1}}
     +--{{Module 5}}
and so on

where {{indicates a transcluded page}} and "quoted text" is entered directly into a page.

You can then re-use the modules in another document, like this:

Code: Select all

Document 2
+--Chapter 1
     +--"Some text introducing Chapter 1"
     +--{{Module 1}}
     +--"Some text linking Module 1 to Module 5"
     +--{{Module 5}}
     +--"Some final remarks about Chapter 1"
+--Chapter 2
     +--"Some text introducing Chapter 2"
     +--{{Module 7}}
     +--{{Module 8}}
and so on

The above is highly simplified, of course, and the true structure will have more levels to the hierarchy.

Regarding the problem of getting a suitably ordered list of sub-pages... You don't have to use <splist/> if the list is going to end up in an undesirable order. It only takes a little extra work to list the sub-page names manually in the order you want them.

Incidentally, I don't know whether you have already come across it, but this is the manual page for the sub-pages extension that is installed on the wiki: http://www.mediawiki.org/wiki/Extension:SubPageList3

Hope that helps.

Chris.

[daverii]

Once again, thank you Christopher.

You are correct, even I had begun to see that using subpages so freely was foolish, although only last night when I was considering how to 'prettyfy' the Main Page did I find your Most Popular Pages approach. Thanks for the reference to SubPageList3, I had not found them. Still somewhat unclear about the relations between Mediawiki and docs.joomla - I think that the latter is an instance with a slightly different set of properties.

Strategic advice is required I think. I am viewing a conflicted problem, that is, one in which there appear to be a number of sets of competing requirements. I will draw Amy's attention to this thread to see if I can get her to contribute too.

Making pages vs Understanding the tools.

I am retired so it is not a problem but there is one push to put ink on paper vs another to understand how the pages fit together.

Defining user groups vs Thinking about the overall scheme

I believe that moving from the particular to the general is hard work. On the other hand, time spent contemplating the general is often seen as unproductive. Designing User Manual, Recipe Book and Help pages to be part of a single piece seems v attractive to me.

I hate wiki vs Writing in Word

I get a strong feeling that we have turned the world off by thinking about a wiki - not sure what they would prefer. On the other hand wiki chunks make an excellent source for web pages, e.g. Help, and could thus be adapted to a User Manual, etc web site.

There are more but of lesser importance.

My approach at present is to

• Use Chunks for the transcluded content (is there a difference between them and pages other than the Namespace?)
• Use Article Wizard to help folk feel easier about writing the Chunks.
• Allow free contribution of Chunks.
• Provide an Agenda (TOC) for where work is needed.
• Use a Page needed Go To Wizard chunk to indicate where wanted pages.
• Manage the Overall Structure by manually built lists as Most Popular Pages.
• Apply Joomla styles to produce consistent appearances. (Is there already a 1.6 palette?)

Priority? To make it easy for folk to contribute.
Risk? In some way that will prove to be a reputation damaging blind alley
Choice? I read that 1.6 will be 60%+ like 1.5 - is that true? where do I find a list of inclusions & exclusions? Build a 1.6 Manual based on 1.5 as a target for editing to make a fit for purpose Manual.


Please offer advice to a new boy on the grounds of your Joomla backgrounds.

Thanks

[AmyStephen]

Tony -

This community is very fortunate that you have decided to participate with us! Thanks for asking for my viewpoints on this. I do have a bit of concern but I think you have my concerns firmly in mind.

The wiki holds great promise as an instrument with a low barrier of entry that is useful for crowd sourcing documentation. In other words, it can be very easy to use which means more people will do so.

The wiki also appears to be extremely sophisticated and difficult to use, without spending lots of time learning about all of it's capabilities. A smaller group of people, with interest and time, might be able to explore those areas in an attempt to create re-use and structure with the contributions.

My concern is that we try to make it easy for people to contribute to these important effort in a way that their work has value and it's something they can do in a couple of hours. We can recruit with those things in place.

So, Tony, you have found in your work here that much of the documentation is already in place. We just need to link to it? And, fill in the empty gaps?

What is required to get to the point where the Table of Contents is linked to the existing content, and the updates needed are clearly identified? When we reach that point, we should be able to explain (document) what people need to do to get involved. Then, we could even schedule a Documentation Event and try to get as much written that weekend, as possible, plus have a group who understands where to go from there.

I imagine reaching that point of clarity will require a great deal of work. Is that true, Tony? Or, do you have a good handle on that already?

I'm excited for this effort and thank you for your leadership. Offering users basic User Guide material when 1.6 rolls would be awesome!
Amy

[daverii]

Amy

I think that can be achieved fairly simply and will endeavour to get there fairly promptly.

My view of the wiki is that, like other computer languages I have encountered, it is a pain to get your head round - but once there it is pretty quick to write.

Two consequences

• Other contributors should be provided with an easy route to writing.
• Chris can perhaps guide my hand as to the most effective route to achieving this.

Chris, following a challenge from Amy I have made an example which might also serve as a basis for Joomla! 1.6 Manual. Do you have any advice about where I am straying from the straight and narrow?

[AmyStephen]

Awesome!

You have this well under hand. When you have reached the point that you and Chris are comfortable with approach and have a simple list of what remains to document, then let's get a documentation event organized to kick this off.

I am very impressed - and pleased. Thanks very much for your contributions!

[dextercowley]

Regarding the editing in the Wiki, I have been using the wikEd editor lately and it seems to be an improvement over the standard editor. Here is a link: http://en.wikipedia.org/wiki/User:Cacycle/wikEd

I am also using a program called Commonist (http://djini.de/software/commonist/) (probably get me on an FBI list or something) that lets you upload image files (e.g., screenshots) in batches.

I haven't gotten around to writing instructions for installing these yet, but I can do it if there is interest. Mark

[Chris Davenport]

You are correct, even I had begun to see that using subpages so freely was foolish, although only last night when I was considering how to 'prettyfy' the Main Page did I find your Most Popular Pages approach. Thanks for the reference to SubPageList3, I had not found them. Still somewhat unclear about the relations between Mediawiki and docs.joomla - I think that the latter is an instance with a slightly different set of properties.

docs.joomla.org is a MediaWiki instance, although it has been customised a lot, so it's not what you'd call an "out of the box" installation. One of my goals for the translation wikis is to cut down on the amount of customisation and to get all the customisations documented. I am part way through doing that, but the list of non-standard setups is already running to several pages.

Making pages vs Understanding the tools.

I am retired so it is not a problem but there is one push to put ink on paper vs another to understand how the pages fit together.

I can understand that and if people want to start by putting ink on paper that's fine. But in my experience, it's much harder to integrate such material into the main body of the documentation later. In effect, you end up with isolated islands of documentation that go stale because nobody's keeping them up-to-date. The text they contain is difficult to re-use because it has been written for a specific context so you end up spending a lot of time re-writing the good parts and removing the duplicated parts (or it simiply gets abandoned). In other words, it's just not an efficient way to produce and maintain documentation. But if people want to do it that way, then I certainly won't stand in the way.

Defining user groups vs Thinking about the overall scheme

I believe that moving from the particular to the general is hard work. On the other hand, time spent contemplating the general is often seen as unproductive. Designing User Manual, Recipe Book and Help pages to be part of a single piece seems v attractive to me.

In my experience it helps a great deal to have a "content plan", which might be thought of as being similar to a table of contents. It helps because it shows you what modules need to be written. But more importantly, it can tell you about the extent of each module, especially if you have multiple content plans for multiple output documents since you can see where they overlap. So with some topics you might be able to write large modulles, but for others you might need to write smaller modules so that they can be re-assembled in different ways to create different output documents. Of course, the modules can and should be hierarchical, with smaller modules being more likely to be re-used than larger ones.

I hate wiki vs Writing in Word

I get a strong feeling that we have turned the world off by thinking about a wiki - not sure what they would prefer. On the other hand wiki chunks make an excellent source for web pages, e.g. Help, and could thus be adapted to a User Manual, etc web site.

Yeah, some people just don't "get" wikis. But apart from some expensive proprietary tools, I have yet to find a better solution for single-source, modular documentation which keeps the barriers to participation low.

My approach at present is to

• Use Chunks for the transcluded content (is there a difference between them and pages other than the Namespace?)

The Chunk: namespace is really just another Template: namespace. The advantage of using a separate namespace for chunks/templates is that they are not searched (by default), so anyone searching for content on the wiki will only see the assembled pages and not the chunks. Remember too that *any* page can be transcluded into any other page; the source pages don't have to be in the Chunk: or Template: namespace. Why have separate Chunk: and Template: namespaces? I think the idea was to keep document modules separate from "utility" templates, like ambox, but it's not been a well-kept distinction.

[*]Use Article Wizard to help folk feel easier about writing the Chunks.
[*]Allow free contribution of Chunks.
[*]Provide an Agenda (TOC) for where work is needed.

If you have the (empty) pages already created then you can add them to a category, like the [[Cookie jar]] category. That way the wiki does all the work of maintaining the list of pages that need to be worked on.

[*]Use a Page needed Go To Wizard chunk to indicate where wanted pages.

See above. Probably better to let the wiki do the work.

[*]Manage the Overall Structure by manually built lists as Most Popular Pages.
[*]Apply Joomla styles to produce consistent appearances. (Is there already a 1.6 palette?)[/list]

It's best to keep CSS and HTML markup out of the wiki. The home page is an exception, but that's not really part of the documentation itself.

The other thing I've learnt is not to put header in the chunks themselves. The main reason is that you can't be certain of the header level that is required when you transclude a chunk into another page, but it's also possible to give a transcluded section a different heading from the one suggested by its page title.

Choice? I read that 1.6 will be 60%+ like 1.5 - is that true? where do I find a list of inclusions & exclusions? Build a 1.6 Manual based on 1.5 as a target for editing to make a fit for purpose Manual.

I don't think that anyone has yet compiled a list of differences between 1.5 and 1.6. There are certainly lots, and far more than would be expected for a point release. There is also still substantial development work going on, so it's nowhere near complete or stable yet. That's why I wouldn't recommend starting on the help screens until at least the first beta release.

Chris.

[Chris Davenport]

Chris, following a challenge from Amy I have made an example which might also serve as a basis for Joomla! 1.6 Manual. Do you have any advice about where I am straying from the straight and narrow?

Looks very pretty.

One thing I have noticed you doing recently is using external links to link to wiki pages, rather than internal ones. For example, you often use

Code: Select all

[http://docs.joomla.org/Page_name]

instead of just

Code: Select all

[[Page name]]

Apart from being easier to write, the internal form is preferred because it enables the wiki to do more clever things, like being able to give you a list of all pages that contain references to a particular page (the "What links here" link that you can see on every page).

Chris.

[daverii]

Chris

Thanks for all of that. I am getting my head round the wiki and modular documentation and I think I can see how to approach the overall problem.

Current plan is to have three page types.

• Manual Head Page with references to
  • Chapter Lists
  • Contribution Advice
  • Work Wanted
  • etc
• Chapter Head pages (and maybe sub Head pages) with Commentary and Contents List
• Content pages

The top two levels will be Main Page like, the Contents pages will be Wiki page like.

The top two will be hand crafted lists with commentary sections.
The contents pages will be Chunk assemblies.

I am going to prefer Chunks to Templates or ordinary pages.

Sample set in the next 48 hours.

Once again thank you.

[Chris Davenport]

Regarding the editing in the Wiki, I have been using the wikEd editor lately and it seems to be an improvement over the standard editor. Here is a link: http://en.wikipedia.org/wiki/User:Cacycle/wikEd

I am also using a program called Commonist (http://djini.de/software/commonist/) (probably get me on an FBI list or something) that lets you upload image files (e.g., screenshots) in batches.

I haven't gotten around to writing instructions for installing these yet, but I can do it if there is interest. Mark

WikEd is already installed on docs.joomla.org and you just need to select it in your user preferences. I've been using it for several weeks now and it seems quite good. It might help some of the wiki newbies, although I did struggle to understand how to use the search tool. I haven't tried Commonist, but then I rarely upload a lot of images.

For those wedded to their word processors, OpenOffice Writer can export in MediaWiki format (click File -> Export, then select "Mediawiki (.txt)" from the drop-down list. There is also the Sun Wiki Publisher plugin (http://extensions.services.openoffice.o ... ipublisher) which allows ODT documents to be exported to the wiki automatically. It works fairly well, although due to our use of Geshi and other extensions, it usually requires some manual fixing up after a page has been pushed into the wiki. I used it for most of the pages in the template tutorials area.

Chris.

[daverii]

Chris

I would like to use internal links but maybe I lack a wiki skill.

[url text] gets the link through text.

[[page_name text] gets page_name text.

Can I use internal links and get short link text?

[dextercowley]

@Chris: I didn't know you could export from OO to wiki format. That's really great!

@Tony: for internal links, here is some help: http://meta.wikimedia.org/wiki/Help:Link

The basic format is [[text you want to display|text for the link]] to control the appearance of the link.

Mark

[daverii]

Mark, thank you. The time I have spent hunting for that just proves how useless I am!!

I was wondering while walking today if you have a nomenclature scheme for uploaded images. I hope to use the modular documentation approach to build the Manual for 1.6. It will require a large number of images with a strong intention to reuse where possible. A simple convention to allow users other than the first to find appropriate images would be a great help.

Any tips?

[dextercowley]

Hi Tony. Are you a member of the Documentation Google Group? If so, here is a link to the thread where Chris proposes a naming convention: http://groups.google.com/group/joomla-d ... ae2f0c901a

If you can't read the link, let me know and I'll paste in the relevant text. Basically, the idea of the naming is to (1) make sure names are unique and (2) if possible make image files re-usable. Personally, I have never been able to re-use any files, but at least the convention Chris proposes accomplishes (1).

By the way, the Open Office export to wiki format looks pretty cool. If you don't use OO, you should give it a try.

Mark

[daverii]

"Well...how did I get here?"

Indeed. It appears that I am and that I can access that link. One of my challenges is that at almost every turn I find another whole Joomla! resource. If only I had started 5 years ago.

That is very helpful to what I am up to.

Thank you.

[daverii]

Well, that proved to be wrong. I can see the link but I am not a member of the group.

Were I to be a member of that group I could, for example, see the spreadsheet you refer to in your response to Marieke. If I were to join that group it would be best to use my gmail email which is [email protected].

Cheers

[Chris Davenport]

I was wondering while walking today if you have a nomenclature scheme for uploaded images. I hope to use the modular documentation approach to build the Manual for 1.6. It will require a large number of images with a strong intention to reuse where possible. A simple convention to allow users other than the first to find appropriate images would be a great help.

I copied it onto the wiki here: http://docs.joomla.org/JDOC:Image_naming_convention

Feel free to use and update it.

Chris.

[dextercowley]

Thanks, Chris. That will be very helpful. Mark

[daverii]

I am doing experiments to see how this could all hang together.

Rather than following my last effort of producing 100+ rather silly files I have attempted to write some kind of specification. May I ask you to have a look and see how it can be improved?

Thank you for all the help and support.

Attachments are the same thing in two different formats.

[daverii]

Please help with wiki markup.

I want to use {{Chunk:Name}} as a template.
I am experimenting with {{User:Addacumen/Page04}} as a template.

Both produce links to the already existing page rather than transcluding the page. Just using a page name works but I want to get away from the main namespace.

What am I missing?

Thanks for your help.

[Chris Davenport]

I want to use {{Chunk:Name}} as a template.

That should work. Check your spelling?

I am experimenting with {{User:Addacumen/Page04}} as a template.

Transcluding from the User: namespace was blocked. But I've just removed the block so try it again now.

Just using a page name works but I want to get away from the main namespace.

The page name on its own looks for the page in the Template: namespace. In other words, {{Name}} is the same as {{Template:Name}}. To transclude a page called Name (which by default is in the Main: namespace) you must do either {{:Name}} or {{Main:Name}}.

Chris.

[daverii]

Thank you Chris.

I want to keep my experimenting in the User namespace if possible.

[daverii]

Things are beginning to come together.

Here is the top of the draft site.

Next to expand to page level from Chapter head level. Needs me to build the template and join everything up.

Then tidy up the mess I have been making.

Then populate the pages from pre existing material.

And, thank you, Chris I have no further need to experiment on User: as a template area.

Thanks for all the support

[daverii]

I think things are going splendidly.

I have discovered <categorytree> which is easy to use and potentially very helpful to the documentation process. However, when I apply it to Joomla! 1.6 I just get a long list of pages which I would like to put in their sub categories.

My plan is to have three intersecting category dimensions.

• Joomla! 1.6 and its sub topics
• User experience - beginner, intermediate, expert
• Topic/Page preparedness - created, in progress, please review, fit for purpose

Can you please explain to me any tricks of the trade to do with creating category trees?

I propose doing the same thing for topics/chunks and for images so that contributors can more easily find their way to what work is to be done.

Thanks again,