Reading Wiki

Searching: text

Now a user can:

search in the local mediawiki search engine,
look for categories and navigate them,
use google to search in the wiki

Today the best option is the (3). Categories are absent on 2000 pages out of 4400..., and other half is probably worth a check :)
We should try a specific search extension

Searching: Semantic wiki and Tags

Semantic wiki extension is the best solution to me: we could add PROPERTIES to data in the pages, and then query for them. Instead of having a whole page categorized as "Blender 2.46" we could assign the property "blender-version:: 2.46" and then search every page related to blender versions major then 2.46. If we are looking for french tutorials related to mesh editing in blender > 2.37 we can easily add properties and look for those.
Furthermore, properties would be very useful in the Reference section, since we could set the properties "mesh-editing", "face","command" to "CTRL-F" and "mesh-editing","edge" to "CTRL-E"and later we can search for mesh-editing commands in edge mode. Adding the "view" property, we could ask the wiki what CTRL-E does in the "3D view" or in the "NLE editor".
I think the Special:Ask page in the semantic wiki extension in very useful. A property type can be set to page, string, number, among others. The blender-version property, for example, could be set to number, or string.
As an example, see this semantic query: if this was a query in blender manual, if could have been

[[Blender-version:: >2.46]] [[View:: 3D]] [[Selection-mode::Edge]][[Tools:keyboard]]

Searching: typos

This may be sci-fi but... :) A typo makes a word unreachable from search engines!
How many typos do we have? Many? A few?
I note here to try a script to make a list of all the words in the wiki and confront them with some dictionary with an API out there, in order to make a list of possible typos. If we had a Semantic wiki, we should try to modify the text in wiki giving the "property:typo" to suspect words and then let tusers de-tag those that aren't typos but new or strange but real words (this would silently put them in a special list as a reminder for future 'dictionary-scripts' passes), so to have a near to perfect text search.

Short URL

Elimination of /index.php/ in the url might help keeping the URL short and more communicative.
Problem is maybe removing it now just break all the bookmarks and links all.over?
A solution might be to clone the wiki and start working on the new one with short-urls from Blender 2.50 on.

Broken links

Is there a way to detect these? The best thign would be a page with the summary of all the broken links, in order to let editors to check them.
They should have a different color if possible, in order to be evident in the eyes of editors even if they just navigate the wiki.
Also, in case they are a lot, how to advice site owners? A call on Blendernation?

<bebraw>The broken links issue is probably something a script could handle
easily. That's something worth an afternoon hacking with Python don't
you think? :)

Overlap beetwen development docs in CMS and wiki

   <bebraw> there is some overlap in dev docs between blender.org
            and the wiki. they should be probably unified somehow?
   <bebraw> migrate blender.org info to wiki?
<mindrones> ok, I'll ask ton :)

I've asked Ton in chat and he said ok, we have to see what have to be ported, especially since there's this "hackers guide" that seems to be related.

Merging of BSoD (in Tutorials and Manual)

People starting now with Blender may not know what BSoD has been, and so they may think it is for advanced users.
I'd put that effort into Manual and Tutorials, maybe with a template to put a phrase and a link that helps understand what BSoD is.

   <bebraw> I would probably merge BSoD docs to rest if possible
<mindrones> yes me too
<mindrones> that's 2006 tho, but yes I'd propose that
   <bebraw> some of it is still quite nice (part of it ended up in essential blender)

Merging of Game Engine with other features of Blender

I don't think it's worth keeping Game Engine separate from the rest of them manual/tutorials, as since I began with Blender having it outside of Manual seemed confusing to me. I'd explain that as all other features.

<mindrones> then we have gameengine
   <bebraw> in a way it feels like a part of main docs ...
            it's hard to say what's right in this case though
<mindrones> I'd say it's in
<mindrones> but someone doesn't compile it in
<mindrones> has official release always GE in?
   <bebraw> yeah

Section map

Give a site map, in order to let the reader to know where he/she is in the "tree".

<mindrones> I've thought if we give people a "section map" they
            realize their structure is flat
<mindrones> so we might use some very easy script to produce
            graphs with links, like this
<mindrones> http://www.wickle.com/wikis/index.php/Graphviz_extension#How_to_make_autolinks_.28all_nodes.29
<mindrones> not on the whole wiki, but per-section
<mindrones> there is this small php code 
            http://mwextensions.cvs.sourceforge.net/viewvc/mwextensions/mediawikiextensions/Graphviz.php?revision=1.1&view=markup
            to enable this
<mindrones> http://download.mindrones.com/blender_wiki_081213.png

Uniformity and cross-checking

If we achieve a good uniformity in the trees structures, we can check the presence of informations among different sections even across namespaces (example: subdivide mesh has informations spanned through Manual/Tutorials/Reference/Scripts/maybe BlenderDev, then Relese notes, etc...).
This would let a reader check if there are project in development in a certain area, especially if he's going to post a feature request. So it could be worth to imagine a reader-workflow based on the user experience.
Example:
in a given section, "mesh subdivide",

a beginner looks for a manual, checks commands in reference, then tries to follow a tutorial;
an experienced user looks at manual to check if there are changes in release note, or new projects, then he might want to post an idea, or he finds an error and post a comment;
an editor might read about that error and wants to change things in manual, tutorial and reference all at once.

All of them want to cross check things, so having the same structure can help.

Proper indentation in the Table Of Contents

A problem is it is not indented like it is in a fresh mediawiki installation, is this by design?
It would help comprehension a lot.

Offline version

Probably an old idea.
A problem I see is that if a wiki version starts to flow in peer-to-peer we might have old version of the manual around after a while.
Also, people might be less prone to buy books form Blender Foundation;)
But, in some occasions it could be useful, like on a train, and offline in general.
Possible formats are pdf of course but also a html version in forlders and a chm file can be quite useful.
There are a couple of extensions for this.

Standardized "end" chapters

At the end of most of wikipedia.org pages you can find "See also", "External links", and "References" chapter (see examples 1 2 3).
These are very useful most of the time, so I'd propose to have:

a "See also" section to report related arguments in wiki.blender.org itself,

a "External links" to report useful links, and to use an anchor to the link when we want to cite a link in the text, in such a way that there is a "repository" of links in a unique place (at the bottom of the page), so that we always know where to look at for external links). An idea could be to ask blendernation their links, or have their links added automatically (via template?), or to have blendernation links to appear as they were Ads...

a "Reference", links to Reference pages used in a certain page of the Manual or Tutorial, as a summary of commands used in that page.

what else?...

Imagemaps to navigate manuals from Blender screenshots

Use of Imagemap extension to insert Manual links in blender screenshots, in order to visually learning Blender's interface.
It would be fantastic if we can visually obscure parts of the image in parts away from the mouse (with Javascript?).

Code syntax highlighting

With GeSHiCodeTag extension you can see code with a proper syntax highlighting, like we see on http://pasteall.org. Another example is here.

Read wiki inside Blender

Nowadays people is talking about click on Blender elements to open a browser and read Blender's documentaion.
Ianwill told me he talked to Ton about having a toggle that shows a "?" on the mouse pointer to click on Blender interface elements to do this.
It would be just a great idea, but I'm concerned about continuously switching between Blender and Firefox.
I had an interesting chat with bebraw about this. The basic idea is below.
At the present day:

we can retrieve wiki pages content with mwclient
Example at the python shell:

>>> import mwclient
>>> site=mwclient.Site('wiki.blender.org',path='')
>>> page_wikitext=site.Pages['User:Mindrones'].edit()
>>> print(page_wikitext)
==me==
* website
:http://www.mindrones.com
:http://blender.mindrones.com

==doc==
* [[User:Mindrones/blender-wiki/proposal | wiki reorganization proposal and ideas]]

we can parse the wikitext and create python data tructures, or html/xml/... (it depends on the script of choice) and get the text as we want to render
we have a a text editor with Text plugins which means we can put the text to be rendered in the text editors and add markers: if "marker" here means "link" we can make a Text plugin that let us click on marked text (urls) to eventually open with this same mechanism a new page from wiki
we have an Image Editor (IE), so we can download images from wiki and put them in the IE when the user clicks on some icon embedded in the text. I'd put only one image per line and by default I'd show images on the line where the cursor is. If the IE isn't open we can even avoid to download the images.

This way, with a simple python script we can retrieve wiki pages and show text and images based on where the cursor is in text-editor. It would be basic a basic wiki browser, without javascript and CSS, but it may work :)

The problem bebraw has seen with images is where to cache them in python, maybe PIL lybrary may help here. Anyway, since most of the images in Blender's wiki are screenshot, we talked about the fact that probably after 2.5 it would be much easier to tell the interface to pupup elements images, letting OpenGL generate them on the flight instead of download bitmaps from the web! It would be a matter of define tags in certain points of the wikipages, to let the Text plugin to understand what it has to ask Blender to generate. Is there a way to have this embedded in wiki without ruin the webpages? Wiki templates are ok for this?

We (bebraw and me) are going to make a proof-of-concept with mwclient+wiki-parser, withouth images.
An idea is also to use his BUI (Basic User interface) to render a small set of html elements in the scripts window. We'll see.. :)

Feedback and help would be appreciated here :)

利用者:Mindrones/Wiki/Proposals/2009/Workflow/Read

目次