User:CirTap/DocCamp MKII

Before we run the next DocCamp in March 2008 there are some things to do. Here's my list, in no particuar order:

Template cleanup

Cleanup and free Template: from JTTP chunks. That namespace is not a content namespace even if it's convenient to use ;)

Yes, out inexperience is showing through. ;-) Chris Davenport 18:53, 14 March 2008 (EDT)

• discuss whether we should open a dedicated namespace to hold the "non prose" and "data" chunks such as
  • tables and lists
  • screenshots with descriptions
  • stuff that does not conflict with document outlines (no headings/sections)

This would also help to organise and find such pieces. Their pagenames should be short, ie. "Admin table colums" instead of "List of tables columns in Administrator screens" -- you get the idea :)

Yes, I think that's a good idea. Perhaps separate namespaces for the different chunk types? (eg. Examples, figures, tables, procedures, etc.) We also need to create guidelines for chunk naming. Chris Davenport 18:53, 14 March 2008 (EDT)

Not sure about the namespaces. They are not supposed to be used for categorisation... got to think of the pros + cons :)

I'd (also) use subpages for "alternative" versions, or the audience level, of a chunk where applicable.

• Data: "Chunk:Contacts/Admin table columns", "Chunk:Contacts/Basic Parameters", ...
• Prose: "Some Contact procedure/Beginner", "Some Contact procedure/Advanced", each transcluding some "Chunk:Contacts/*"
• Page: "Messing with Contacts (Beginner)" transcluding the "Chunk:*/Beginner" chunks
• Page: "Messing with Contacts (Advanced)" -- same as Beginners but parts replaced by or interleaved with additional "*/Advanced" chunks.

I decided to use Labeled Section Transclusion (LST) for the Framework and assoc. Landing Pages instead of the much more complicated (but also more powerful) DynamicPageList (DPL). LST can be used more intuitively in daily-use and it's easier to grasp than DPL, imho. DPL might still be useful to compile "the big documents" :) I'll create a small set of example pages with LST for you to see what I have in my crazy mind :) --CirTap 20:30, 14 March 2008 (EDT)

---

ok, I thought about spreading chunks to distinct namespaces

as a reminder, we already have Tutorial:, although some of the early copied pages are still broken. The internal namespace identifier wasn't configured at that time and MW now thinks such pages belong to Tutorial (id #102) but the database contains the identifier of the Main namespace (id #0). I'll re-assign those entries manually to #102 in the database 'cos it's utterly annoying to delete them using MW (need to move 'em to another namespace, drop the generated redirect, move 'em back, drop that redirect, too, to finally delete what was basically an empty page)

• if you insist to go for a new set of namespaces, don't use plurals, like the internal namespaces aren't called "Images" or "Templates" either, because the page name looks odd if it reads Lists:Parameter when there's in fact just one tiny list on that page.
• I'd prefer to go with Chunk: only. A chunk still remains a chunk although it may belong to a certain category of chunks. If you insist again on using different "prefixes", we can add an alias for each type instead (List:, Table:) like JDOC === Joomla === Project. That'd make an entry read as {{List:jdoc include types}} but it'd belong in the same namespace identifier as Chunk:.
  Drawbacks: with aliases there's no (physical) difference between List:Foobar, Figure:Foobar, and Table:Foobar
  Advantage: the Search facility works on a namespace basis. If you look for the available "Foobar" chunks and we have "real" namespaces of List, Table, Figure, Example you'd need to select each single namespace in order to find all "Foobar" items ("Was it a Table: or a List: ?), which brings me back to use subpages in order to classify and organise them.
  An alias doesn't literally show up in Special:Search, but "Chunk" would. Subpages such as Chunk:Foobar/list, Chunk:Foobar/table, Chunk:Foobar/procedure will all be found 'cos they share a common name. And on top: access control would be easier if there's only one Chunk rather than many ;)

Main cleanup

• move to Main: where {{Larger article segment}} was used (in error?) instead of the recommended syntax {{:Larger article segment}} (leading colon!) or {{w:large article segment}} (local interwiki) for unambigious links in transcluded documents.
  • page history will tell us who created a chunk, so we can tell those users to use the correct syntax
  • I'd like to lock Template: (if possible) for editing by regular users, comments will be allowed in Template_talk:

Ok, I think I understand. So what you're saying is we should put wiki templates that are merely re-usable text chunks into Main: and leave Template: for the templates that are like subprograms (eg. Ambox)? Sounds like a good idea and if so then locking Template: makes sense too.

exactly!

Chunks with "prose" ~ re-usable text should stay in Main: as regular content so they can still be found via search + Google (and "What links here" in the sidebar can be used to find the documents that refer to it). The other, small "data lists", may go to the new Chunk: namespace -- which I'd configure to be not searchable by default to not polute search results.

I presume the "audience level" documentation you're after will primarily transclude the "prose chunks" (yet another term), who themself transclude i.e. general stuff like "Chunk:Admin table colums". --CirTap 19:24, 14 March 2008 (EDT)

• add {{redirectstohere}} to targets of Category:Landing Pages named differently, i.e. add to Template that "Themes" redirects there, to keep users from looking up "Themes" anyway only to find out that Themes keeps taking them to Template ;)

Categorisation

There's a big lack of it and it needs to be improved. Every page should at least belong to one category. We need to tell people that unlike some famous and well beloved CMS, MediaWiki can add a page to many, many categories at once and that categories can be nested.

Having category pages is like having built-in "landing pages" and instead of compiling those lists manually, let MW do that!

In the near future I'd like to use/install the Semantic Mediawiki extension which by itself can be extended

Example:

• Screen Captures, each pages listed there should rather go to Category:Screen captures and a category named after the sceen itself, e.g.. [[Category:User Manager]]. In this case one additional top-level category should also be present, either
  1. [[Category:Administrator]] or
  2. [[Category:Back-end]]
• full list here: Special:Uncategorizedpages
• Special:CategoryTree

Category:Tutorials

This category most likely doubles the content of the Tutorials namespace and probably lacks many entries 'cos it's maintained manually (see previous issue). The letter T is pretty crowded due to the naive usage of the Category tag.

We may either

1. scratch this category and have a Landing page instead that features a short list of the "most important" tutorials and then transcludes {{Special:Allpages/Tutorialss:}}

Pro: simple and always up to date

Contra: there's no ABC register generated by that list.

1. keep this list but make sure that each entry uses [[Category:Tutorialss|{{PAGENAME}}]] (or a proper sortkey) to get a nice ABC register

Pro: uses the built-in system, the category page is easy to navigate, not limited to Tutorials namespace, allows for sub-categories. See Category:Wiki Templates which features pages from the Template namespace

Contra: requires humans (or Bots) to be maintain and in sync with

Dead end pages

Too many pages without links. I believe that every page can feature at least one link to another existing page in the wiki. Special:Deadendpages

Image cleanup

see also: Styleguides below

• find people to re-encode present images to a smaller file size, i.e. compare Image:New_inkscape_image_800x600.png (original file: 150kb, re-encoded: 25kb)
  • introduce free tools that do so
  • delete old, fat images, once a re-encoded smaller file is available

Categorisation

top-level categories

• "Screen shots" where full-screen images and admin tablesgo
• param panels at least go to their respective CMPT categories where they will show up as "Media in this category"
  1. Category:Component parameters
  2. Category:Modules parameters
  3. Category:Plugins parameters
  4. Category:Templates parameters

Visitors can drill-down into the sub-categories via the CategoryTree:

+ Joomla!
 + Extensions
  + Components
   + Component parameters
  + Modules
   + Module parameters
  + ...
+ Parameters
 + Component parameters
 + Module parameters
 + ...

JTTP Chunks

• categorise chunks properly and extensive
  • review Categorising a chunk
• organise chunks into subpages
  • by subject ?
  • by audience and personae? (see below)
  • make each subject/audience "subfolder/" (subpage) an index of its chunks
• make use of {{documentation}} to document a Chunk's usage, application, scope, relationship, related Chunks, etc.

Needs some thought, but basically yes. Chris Davenport 18:53, 14 March 2008 (EDT)

Special pages

• introduce and explain the various Special pages that help to find things and to clean things up (transwiki relevant help documents from the MW manual over here to provide specific information and possible differences)
  • ⧼Disambiguations⧽, All pages with prefix, Search
  • Categories, Wanted categories
  • List of redirects, BrokenRedirects, DoubleRedirects
  • Dead-end pages, Orphaned pages, Wanted pages
  • New pages, Oldest pages
  • Long pages, Short pages
  • ⧼Imagelist⧽, Gallery of new files, Unused files
  • Uncategorized categories, Uncategorized files, Uncategorized pages, Unused categories

Yes. Chris Davenport 18:53, 14 March 2008 (EDT)

Portal

(Re-)Introduce the Portal: namespace, and use the Portal for announcements (to be transcluded elsewhere), publish JTTP, WTP, and DocCamp news. Allow/establish discussions of proposals related to the Wiki documentation projects and their respective contents. Make it a spot for Wiki project RFCs.

• restore the link to the Editor Portal or whatever it should be called in the Sidebar (was: ** portal-url|portal)

I have no idea what the Portal: is about. Will need to read up on that one. Chris Davenport 18:53, 14 March 2008 (EDT)

Framework

Introduce the Framework: namespace (aliased JAPI:), it's contents and page structure

• add/update docs how to add pages
• introduction at JDOC:Framework templates
  • list of specific templates in Category:Framework templates
• locked from editing for regular users, comments are allowed in Framework_talk:

Yeah, whatever it takes. :-) Chris Davenport 18:53, 14 March 2008 (EDT)

Old DokuWiki links

Some links point to the old DW wiki. This special page can help to locate com_jd-wiki URLs and one may probably change those links to a local wiki page -- or it's new location at developer.j.org

JDOC

Introduce JDOC:. This is the preferred namespace prefix to link to pages that deal with the background of Wiki contents and the scope of the various projects (JTTP, WTP, DocCamp). It contains guides for editing this wiki. Documents also explain how things are organised in this wiki in general and inside the projects in particular.

• aka Joomla: (old, still aliased) This namespace was the former alias of Project: but will be deprecated and should be avoided as it may confuse users expecting information about the CMS in links that display the namespace.
• aka Project:, the default systemname. It's the preferred namespace to link to pages with internal and technical documentation about how this Wiki works "for us" and why its organised the way it is. Wiki template documentation pages typically refers to such documents.
  • contains how-tos and guidelines for wiki authors
  • task: cleanup Main NS and move relevant pages to JDOC:
  • locked from editing for regular users, comments are allowed in JDOC_talk:
• introduce the tools available in this wiki for content editors (JS helpers in textarea, wiki templates, extensions)
  • link to their documentation in the offical manual at Mediawiki. If specific information is required on how to use an extension in this wiki it'll be available in Help:.

Ok, I think. Chris Davenport 18:53, 14 March 2008 (EDT)

GHOP to Wiki

Is a migration planned?

Yes, subject to available manpower. I'd prefer to have a solid organisation to the wiki beforehand though. These would probably make good Cookie jar tasks for Doc Camp attendees. Chris Davenport 18:53, 14 March 2008 (EDT)

• test/evaluate "HTMLets" whether it permits embedded presentations and Flash objects found in some GHOP task results (Test Wiki). HTMLets can load external .html files uploaded to a dedicated directory on the server (FTP), and renderes them inside a Wiki page.

tested and works. --CirTap 09:29, 11 April 2008 (EDT)

Wiki Template Project

We started in a rush. With the availability of the Joomla! 1.5 Framework Reference, a large amount of helper templates will become available to support "smart" links between documents and across namespaces and transclusion. The JTTP also has a need for smarter templates beyond using the default transclusion techniques.
This project will be lead by me (CirTap) if there aren't any objections :)

Be my guest. ;-) Chris Davenport 18:53, 14 March 2008 (EDT)

• introduce Project:WTP
  • invite users with skills (or interests) to write Mediawiki Templates to participate
• introduce the most important templates for editors and authors
• introduce the Labeled Section Transclusion extension and encourage its usage in JTTP
• user documentation of Wiki Extensions available here

We (meaning I really ;-) ) certainly need some pointers on how to use some of the cool new templates that you've added. Chris Davenport 18:53, 14 March 2008 (EDT)

Might also be a good place to maintain and coordinate Transwiki for content exchange on help.joomla.org and developer.joomla.org

--CirTap 14:55, 13 March 2008 (EDT)

Styleguides

Screenshots

• naming of screenshot images, recommended file formats (when to use png or jpeg)
• screenshots should not contain too much "white-space" which is of no interest and only eats screen estate, disc-space and bandwidth
  • browser windows should be resized to the absolute minimum
  • relevant parts should be cropped
  • they should not include browser chrome, OS desktop etc.
  • the image color-palette of a "Khepri" screenshot can often be reduced to 256 colors (or less!) instead of millions

Example code

• code examples should be "copy-and-paste", unlike this one which uses variables from thin-air and a custom class that is not needed in this scope

Licencing policies

• application of JEDL needs clarification (Chris?/Elin?)
  • documentation != media != images
• some media + image files already present do not comply with JEDL
  • review of uploaded images, "tag" with acceptable licences if JEDL simply doesn't fit
  • check which files need to be removed due to licence constraints
  • check where "fair use" is appropriate (people's photos)

Self reference

• mentioning "Joomla! Documentation" literally or using {{SITENAME}} could cause a wrong context if the text is used in another wiki (according to JEDL)