Kicking Off

I was a bit before myself - sorry.

I have done some work in this area but I will discuss what is to happen with Chris Davenport before going public. Apologies.

Views: 4

Replies to This Discussion

Permalink Reply by Tony Davis on October 27, 2009 at 4:09pm
Here are some draft ideas for Comment.

A workplace for experiment before including anything in the Documen...

My brief discussion with Chris Davenport led to the conclusion that a 'Go For It' approach was probably best. Numerically the most contributions to Documentation are small tweaks to improve clarity or scope of what is already present. This leaves a requirement to construct a large chunk of words to cover most of the points.

I confused myself as I constructed these two documents.

One is a Table of Contents - it is a story I use if I am telling a new Joomla user with some technical skills about how it hangs together - specifically, how I think it hangs together since I am sure there are bits I do not fully understand.

The second is an approach I use to discuss particular implementations - recipes if you like - which includes the idea that maybe some approaches are not for that particular person at this time. The model that I show does not include 'If you want to do something like this but find this hard maybe you should try this one.'
Permalink Reply by Amy Stephen on October 27, 2009 at 4:46pm
Both the Table of Contents and the Model Page are awesome.

(1.6 doesn't have sections or polls)

Love, love, love.

The way it's organized - you could easily re-use those areas to create many recipes Web sites.

Thanks!
Permalink Reply by Mark W. Bender on October 27, 2009 at 10:40pm
Great start for a TOC.

Something we should consider adding is a sample layout page for extensions, so when new extensions are referenced in the Joomla! 1.6 wiki, they have a template for layout of their data.
Permalink Reply by Tony Davis on October 29, 2009 at 7:17am
It is all becoming a clearer and it begins to look more straightforward if we harness the power of the wiki.

1. The need is fairly urgent. We should put in place a User Manual which will reassure current and potential Joomla! users that the path ahead is not problematic. For example, the concern about database migration.

2. The solution needs some wiki work but it will be:-
-- 2.1 A hierarchy derived from the TOC already shown.
-- 2.2 Multiple versions of terminal leaves for different kinds of expertise
-- 2.3 Blank pages will not really be blank they will have embedded wiki templates on their discussion page.
-- 2.4 A wiki template is the source of text which appears in several places - change the wiki and they all change.
-- 2.5 The blank page wiki template will comprise two parts and will be initially placed on the 'Discussion' page of the blank page.
-- -- 2.5.1 The narrative template - all pages about, say, Articles will have the same narrative template.
-- -- 2.5.2 The page builder template - the standard page layout for Manual pages.
-- -- 2.5.3 To work on the new page copy the page builder template to the edit version of the page and add your text and images.
-- -- 2.5.4 I am looking into an Article Wizard which might simplify this. Anyone who knows how to obtain/build/whatever one please get in touch.
-- 2.6 The User Manual and the Help Pages for Joomla! 1.6 if not blood brothers are at least close cousins. The templates could be made serve both ends.
-- 2.7 If you think this is missing something please let me know.

3. Amy said that two of the TOC elements were not in 1.6. Sorry, that post evaporated. May I be told again? Male absent-mindedness to blame.

4. There are some new sample pages the top one of which can be found here.

5. The top of the pages shows a Joomla! 1.6 warning. This is taken from a template. I propose using a template to indicate the 'readiness' of each Manual page. The template will produce
-- 5.1 Red Label - This page is just beginning and should be treated with great care.
-- 5.2 Orange Label - This page has been peer reviewed by 3 people and is believed to be trustworthy.
-- 5.3 Green Label - This page has been found trustworthy.
-- 5.4 Invisible - The whole Manual has reached Green Label status

6. If, as seems likely, the templates (base data) of the Manual can be used for the Help System I would suggest using the same labelling system for the Help Pages.

7. I would be very grateful if anyone were to create pages they would like to contribute to the Manual. For the moment, I am resisting doing this because my focus at present is working out how the whole thing will hang together. Chris Davenport is in the discussion loop.
-- 7.1 Categories - Every article should be categorized. I am discussing which Categories are needed and how we get them.
-- 7.2 Page names - There are tools which allow URLs to be used to generate Contents pages and Indexes. The easier and more helpful we can make this the better.
-- 7.3 Templates A - Mediawiki uses 'template' in two separate senses. Like Joomla! templates for look and feel, and also in the sense of 'factoids' which appear in multiple places.
-- 7.4 Templates B - In the second sense, since 1.6 is about 70% directly comparable with 1.5, many of the factoids exist. It is a matter of getting them in a form and a place that meets the needs of Joomla! 1.6 User Manual. But, IMHO, that doesn't look like too big a job.

8. For any page contributed please either
-- 8.1 Upload an .rtf version of the page you would like and I shall wiki it. (Is that verb allowed?)
-- 8.2 Make a wiki page but please do not be upset if it is hacked about as the changes are made to it.

9. The changes foreseen here need to be managed by someone with permission to create/modify Categories and Templates (factoids) in MediaWiki. We are discussing that at present but, for the moment, do not have access to those facilities. No problem - much better to think and then act than the other way round.

Sorry for the avalanche. I am retired and live in the mountains of Switzerland where I take long walks each day. They are getting faster as I have to rush home to do a brain dump.

Tony D
Permalink Reply by Tony Davis on October 29, 2009 at 8:02am
Here are samples of the Label templates

Red
Orange
Green
Permalink Reply by Tony Davis on October 29, 2009 at 9:08am
And the Red Label has been added to the Sample pages.
Permalink Reply by Amy Stephen on October 29, 2009 at 9:16am
Tony - I'm loving this. I am going to create a Joomla! 1.6 Template Guide group. I understand you and Chris have a chapter in your outline for that purpose.

So, if you are willing, I'd appreciate you joining the other group and I'll make you an administrator for that group, as well. I think it might be easier for recruiting and group discussions if we have two groups. From an overall perspective, you and Chris will naturally think of this as one effort. So, look for that group, if you have problems with the idea, let me know and I'll remove it.

You are doing fabulous. I have goosebumps.
Permalink Reply by Tony Davis on October 29, 2009 at 10:07am
OK - absent minded and blind.

I do not understand no Sections - do you mean as in Sections and Categories or something else?
Permalink Reply by Amy Stephen on October 29, 2009 at 10:41am
Yes, Sections, as in Sections and Categories, will become Multi-level Categories in 1.6. Sections go away completely.

Polls also are gone.
Permalink Reply by Tony Davis on October 29, 2009 at 1:53pm
There is already some work done on Documenting Joomla! 1.6

These two pages - Screen.config.16 and Screen.installer.16 - appear to be screens built for testing the Help system in Joomla! 1.6

The code behind Screen.config.16 shows how to include a whole page into another page.

They are both based upon equivalent screens for Joomla! 1.5 Help system - Screen.config.15 and Screen.installer.15. Inspection of the code for Screen.installer.15 shows how templates are being used to produce repeated occurrences of the same text. Search for {{colheader| and you will see how it is used repeatedly. In Screen.config.15 the template factoids are used less often - only {{toolbaricon - but I think you can see how the code could be simplified by creating more factoids for the other entries which will appear elsewhere.

During development the User Manual would need an index of the factoids available so that it would be easy to find where resources could be found.

This is the approach I would like to take in what we do.
Permalink Reply by Tony Davis on November 6, 2009 at 4:33pm
Apologies for doing a few somersaults but what is required is becoming clearer.

I would greatly appreciate your views on what is proposed. A sketch of this will be available on the wiki within the next 48 hours.
Attachments:
Permalink Reply by Tony Davis on November 6, 2009 at 4:35pm
The image naming convention described has been moved to the wiki and can be found here.

RSS

Badge

Loading…

Get Badge

© 2012   Created by Amy Stephen.

Badges  |  Report an Issue  |  Terms of Service

Sign in to chat!