daverii wrote:
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.
daverii wrote:
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.
daverii wrote:
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.
daverii wrote:
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.
daverii wrote:
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.
daverii wrote:
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.
daverii wrote:
Use a Page needed Go To Wizard chunk to indicate where wanted pages.See above. Probably better to let the wiki do the work.
daverii wrote:
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?) 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.
daverii wrote:
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.
Please help with wiki markup.