[Bf-docboard] How to move the wiki to 2.6+

Thu Nov 3 17:59:06 CET 2011

Hi,

opening a new thread to separate from the thread about 2.3 -> 2.4 issue
(http://lists.blender.org/pipermail/bf-docboard/2011-November/003756.html).

On 11/03/2011 10:51 AM, Brecht Van Lommel wrote:

> I think perhaps the current use of namespaces contributes to the problem?

Namespaces in mediawiki are like "groups" of similar pages, for example:

- Doc:2.4/Manual and Doc:2.5/Manual are in the same namespace (Doc),
- Dev:2.4/Source and Dev:2.5/Source are in the same namespace (Dev).

> Right now the 2.4 manual is in Doc:Manual, 2.5 in Doc:2.5/Manual and
> 2.6 in Doc:2.6/Manual. This way the latest version always keeps
> changing URL, and it needs to start again rising in the rankings. More
> logical to me would be that we'd now have Doc:2.4/Manual,
> Doc:2.5/Manual, and Doc:Manual for 2.6.

We have debated very long about this in #blenderwiki. There are
different possible approaches, see below.

= Possible approaches =

== Legenda ==

* series = 2.4, 2.5, 2.6, ...
* versions = 2.49, 2.52, 2.61, ...

== Approach 1 ==

Making *copies* of the current wiki, one for each series:
- users update the new series
- old series stay as history
--------------------------------------------------------------------

This is bad because would make new urls (bad ranking), and would
duplicate content, confusing search engines and users.

== Approach 2 ==

Moving the current Doc:Manual to Doc:2.4/Manual; move the current
Doc:2.5/Manual to Doc:Manual, then keep updating Doc:Manual
--------------------------------------------------------------------

This would be ok but would also be confusing about which version
Doc:Manual is about, and the next major leap (say, 2.8 -> 3.0) you will
need again to write a new Doc:3.0/Manual and then after a couple of
years invert new <-> old.

When you do such moves lots of redirecting goes on and all links are
kind of broken. If a website is pointing now to Doc:Manual/Foo talking
about a 2.4 feature, if Doc:Manual/Foo suddenly became about 2.6 their
article might well not make any sense anymore.

Also, some templates and the search engine assume implicitly that no
version in pagename means 2.4; later on this will change again, (no
version in pagename would mean 2.6, 2.7 and so on) and the search engine
gets confused (has to be re-setup, reindexed manually, read: headache)

Furthermore, we would go back to the messy state we were in before
restructuring the wiki: we had 2.32 contents alongside with 2.49
contents, very nasty IMO.

And hadn't we separated clearly 2.4/2.5, the situation would be even
more messy, with 2.32 along side with 2.4, 2.5 and 2.6 documents.

No need to say, animation chapter would have been a disaster, 2.4/2.5
being so different.

== Approach 2 ==

Moving the current Doc:Manual to Doc:2.4/Manual; move the current
Doc:2.5/Manual to Doc:2.6/Manual, and later on move 2.6/Manual to
2.7/Manual and so on.
--------------------------------------------------------------------

We have decided to use this approach for many reasons:

* in a search engines, if you search for "blender manual" you get
different results based on the ranking and you actually can choose which
version you want, you click on Doc:2.6/Manual and this instructs the
engine that more and more people are clicking on 2.6, so probably at
some point it will put 2.6 up

* before the version changes, we do a review and *then* we move to a new
series (next mail will be about this). As it is now, new documents can
appear in 2.6, old one can get reviews in 2.5 and when we move 2.5 to
2.6 we get a complete 2.6 document.

Example: cycles doc is 2.6, when we move 2.5 to 2.6 there will be no
conflicts

* the next major step (2.8 -> 3.0) we just start a new manual
Doc:3.0/Manual and the old one stays there, no need to
cross-move/redirect etc

* as Dan said, this is also better for the search engine, which needs to
find a series number in the pagename

= Re: good URLs =

I think this doesn't apply to this particular wiki because we are using
permanent redirect, which means that then we move a page, we leave back
the old page with a redirect pointing to the new one. This is a 301
redirect, which means that when search engines reach that old page they
are informed that this one is no more and there is a substitute for it.
So if we move from Doc:2.5/Manual to Doc:2.6/Manual, the search engine
will know how to assign the Doc:2.5/Manual ranking to Doc:2.6/Manual.

This way we can move stuff and cleanup, keeping the same ranking.

= How to proceed =

== 1. Manuals structures alignment ==

First of all the new skin is made to facilitate the cross-linking,
meaning that if there's a topic "Foo" in Blender , we should have:

Doc:2.4/Manual/Foo
and
Doc:2.6/Manual/Foo

instead of

Doc:2.4/Manual/Foo
and
Doc:2.6/Manual/How_to_do_Foo

This means, that *where it is possible* we want to keep the structures
2.4/2.x the same.

After 2 years letting 2.5 manual go wild as a sandbox, we need to align
the structures.

I, Bastien, and Francesco will do this during this weekend.

== 2. Manual review ==

Before we move, we also want to review the contents.

Some of the pages have been simply copy-pasted from 2.4 and this is bad.

We actually have the impression that the 2.5 manual is complete, right?
Are we sure?
If we actually delete the copy-pasted pages, we could get quite a lot of
redlinks.

While we will align the structures we'll check on this and report back.

== 3. Manual fix team :) ==

In case we find main problems, we would like to find some help for
writing missing parts and get a general consensus that the new manual is
fine.

We'll try to organize a team to make this, more on this later.

== 4. Dev pages ==

I'd like to have all the dev pages also aligned with the manual
structure where possible, and with series number in their page names.

This will helps us cross-linking from a certain manual page to its
counterpart in the development section.

I'm a bit worried about moving to 2.6 because some of the development
pages will have to stay as "2.5" but these are a few.

I think I'll talk with Brecht about this in IRC.

== 5. Do the move ==

We'll do this after 1, 2, 3, 4.

I'm sure I'm missing something, but I'd be glad to hear from someone
experienced at least a bit with mediawiki, to see if there are main flaws.

Please let's don't start a long thread on this, let's stay on topic and
let's adreess technical problem first, we'll talk about actual contents
after the points 1 and 2.

Thanks for reading down until here :)

Regards,
Luca

_____________________________

http://wiki.blender.org/index.php/User:Mindrones
http://www.mindrones.com