Meta talk:Proposals/MediaWiki optimised for manuals

Hi Ewout,

I'd like to start a discussion on your points here.

---

Problem: Page navigation is done in a bit of a primitive way, the implementation is very week, and it's not very flexible.

Ewout's Proposition: All the navigation (flipping pages) should come from the mediawiki engine. This could be rule-based (when a page is in the index/table of contents, it gets a navigation bar on the top), or tag based, which basically works the other way around: when you add a navigation tag, it appears in the TOC.

Spiderworm: Agreed, it is pretty primitive. It would be nice to have some sort of automatic paging in the system.

However, modifying the mediawiki engine makes it more difficult or impossible to upgrade in the future. If we are OK with not upgrading the engine in the future, we can customize the current engine to our heart's content. However, I do not believe this would be wise, as security vulerabilities are bound to pop up and be patched from time to time, features will be added over time, etc.

A few other ideas come to mind, however. One would be writing a plugin to create that functionality thus circumventing the need to write to the engine's core. I believe that MediaWiki's plugin API would allow something like this to be done.

In my mind, I've got to wonder... is it really worth it? When I was doing Noob to Pro it was annoying to set up the links manually from page to page and update the table of contents, but it was no show-stopper or anything like that. It should be even easier here than with N2P because an entire chapter is on a single page, whereas there were a lot more pages and with N2P.

Ewout: You are mixing terms here now. When I speak of the MediaWiki engine, I mean the system as a whole, not just the core (I would call that the core :o)). Yes I do think that wherever it is possible to get our functionality through a plugin (although I have talked to some devs and they said there are not an aweful lot of hooks... Something to find out though!) we should definately go that way. Don't 'break' the core if you don't have to.

To answer your question if it's really worth it... Well I think it is. It's not a show-stopper but it is annoying (talk to any of the active contributers and they'll agree), and it's still a browser hack. This feature is probably not more than a day's work of coding and it greatly enhances the MediaWiki (the wikibooks people have expressed their interest in this kind of plugin aswell btw)

---

Problem: Internationalisation (i18n) is going very fast, and there's no sensible way to see which pages are out of date. This is probably the most difficult thing to overcome.

Ewout's Proposition: Somehow, the international versions of the manual should be linked > that way, when the English page is updated, you could have an automatically generated message that states the English version of that specific page is more up to date when you are browsing another language (e.g. "This page contains newer information (3%) in the English manual"). Clicking on the percentage would then show the diff (for editors). This is just an example of how it could work of course... Also, every page would have an auto generated link to the foreign version, something that would require a lot of editorial work in the current system

Spiderworm: Whose concern is this? I believe the manual will only be printed in English. Is the translation of the docs anything more than a public service? If somebody is in charge of keeping a translated manual up to date, can't they just watch the English version of whatever pages they maintain and set their preferences to email them when a change is made to thoes pages?

But again, this is probably something that could be done with a plugin.

Alabandit: Practicly speeking sooner or later some one will add a section/chapter to the manuel in a langauge other than english. Will also need to know and be able to translate it back to english. The international user group is growing at an astounding rate, we must not miss the opertunity to bring people into the project who don't speek english.

Ewout: Well, actually according to the rules (who reads them anyway?) it's not allowed to create a newer page in a foreign language, because it makes it much harder to get that into the English version - which is hard enough to keep up to date as it is now!

Although I agree with spiderworms comment that the focus should be on the English version, you should take into account that not everyone is able to create new documentation and those can put their energy in translations. I don't think we will 'lose' any editors to this! I would say that it would be a sin if we don't help these people keeping the translations up to date - making it really a wasted effort!

---

Problem: A system that allows to create dynamic hotkey templates, for example CTRLSKEY becomes an image of a "CTRL" and an "S" key.

Ewout's Proposition: The hotkey template is trivial, but it looks much nicer :o)

Spiderworm: Could be done with plugins probably. I agree it's trivial, but could be a nice touch... somebody want to come up with some nice images?

Ewout: I recall a series of (Blender) tutorials that had exactly these kind of images, but I don't know where that was right now... Anyhow, if something like this is needed, I'm definately willing to create the images.

Oninoshiko: I would be more then willing to try and tackle this problem. It seems a good starting point to getting involved. So, if you want to create some images, I'll give it a go. (Inlight of this offer, I added myself to Bf-docboard)

Oninoshiko This code has been submitted, AFAIK it is done unless I get negative feedback about it.

---

Problem: Offline output formats. Several small projects and scripts are being used to create PDF (http://mediawiki.blender.org/index.php/Meta/Wiki_to_PDF) and CHM (http://blenderartists.org/forum/showthread.php?t=64961), but it could be miles better when integrated well. Perhaps a wiki interpreter inside a blender help system?

Ewout's Proposition: People beg for a downloadable version of the manual, but more importantly, the system could be made in such a way that the output would be very useful for a printable version of the manual (which would be a bit of a nightmare to do currently).

Spiderworm: Well I say we focus efforts on the content so that we can get a printed version out very soon... in the form of a book that can be bought in the blender e-shop.

There are ways to take all content from the wiki or just the User Manual automagically with a script. To any would-be script writers, take a look at this:

http://mediawiki.blender.org/index.php/Meta/MediaWiki_optimised_for_manuals?printable=yes

and this:

http://mediawiki.blender.org/index.php/Meta/MediaWiki_optimised_for_manuals?action=render

By appending "?printable=yes" or "?action=render" to the URL you can get just the content of the page. No reason some script couldn't go through a series of URLs and create a copy of all the content. --Spiderworm 00:38, 1 May 2006 (CEST)

Ewout: It takes a little more than the bare pages - there's some stripping to be done aswell (especially when there's no navigation plugin :o)). I'm not saying that makes it much harder, but this is the most simple approach. The real problem lies in the order and proper indexing etc... This is (again) where the content managenent system that handles navigation and TOC comes in very handy. The info from that system would be very usefull to determine the order and the structure of the manuals content and make it much easier to make (better!) checkouts. --Ewout 07:02, 3 May 2006 (CEST)