利用者:Mindrones/Wiki/Proposals/2009/Structure

---

SECOND DRAFT: feel free to discuss in the talk page under the relevant section :)

---

STRUCTURE for the proposed workflow

Separate "real content" from the rest should give a good structure by itself, especially keep "wrong" content out of searches.
The namespace structure below conflicts with the idea of dividing languages with namespace, we should evalutate what's the best option.
Dividing with namespaces, and putting the actual documentation in a namespace different from (Main) would be a great strategy during the cleaning process: if a content is in (Main), then it still neeed a revision. Also, having just a simple presentation of the wiki structure in (Main) let us quickly see if non-expert users create a new page in (Main), so that we can easily contact them and indicate the appropriate section for their content.

Namespace structure proposal

Doc:

Reference, Manual, Tutorials, including a generic script and plugin howto (single scripts manuals under the "Extensions:" namespace).
NEW: add a "Theory" section (see notes below)

Extensions:

Scripts and plugins catalog, see note below.

Dev:

Development documents

Org:

Blender Foundation and Blender Institute wiki pages.

Meta:

Wiki editors documents

Attic:

Old pages
(useful to remove those from searches because the Attic won't be checked by default)

Note about the Theory section

---

I propose to add a section called "Theory" (or "Tech") in which we explain the techniques behind a certain command or procedure. Mostly this will be related to 3D technique, but not only (think about compositing, mathematics or video editing). Using this separation of contents, users that already have a technical background will avoid to read through a page cluttered with redundant informations (this is an example).
Another chance is to collapse theory sections.

Note about dualities Tutorial/Manual, Manual/Theory

---

I like a lot the duality between Manual and Tutorial we see in the Manual index.
I think we should have "Theory" links in manual pages, and "Manual" links in Tutorials pages, so that readers that prefer to start from a tutorial in each moment can jump to the manual part, and then eventually to the Theory part, while readers wanting to learn from the theory can see practical examples of a piece of theory in Manual and then in tutorials.

Note about Extensions:

---

Now scripts are under /Script/Manual, while they should be under /Script/Catalog/...
See sections about scripts tracker and plugins tracker

Structure proposal

Each chapter title is a page itself, eventually containing an introductory text and the index of the chapter.
Motivations for scripts and plugins structure are here.

Doc:<language>/<version> (each branch has the same structure of /Manual)

/Manual

Introduction

Installation | The Interface | Scene Management

Interaction in 3D

Navigating in 3D Space | Manipulation in 3D Space

Modeling

Objects | Meshes | Curves | Surfaces | Text | Meta Objects

Modifiers & Deformation

Modifier Stack | Objects | Meshes | Physics

Lighting

Lamp Types | Lighting Rigs | Shadows and Halos | Radiosity

("see also Materials->Ambient Light" and "see also Worlds->Ambient Occlusion" are ok in the "see also" section in the Lighting index-page)

Worlds & Backgrounds

Materials

Shaders | Raytracing | Material-Nodes | Ambient | SSS

Texturing

Textures

UV Unwrapping

Animation

Basics Animation

General Principles and Tools | Animation by Moving Objects | Animation by Basic Deformation

("Other Resources" can be put in the "see also" section in the Animation index-page)

Character Animation & Armatures

Constraints

Advanced Animation

Physical Simulation

Rendering

Compositing

Video Sequence Editing

Extending Blender

Python Scripts

Bundled | External | PyNodes | Pydrivers

Plugins system

Texture | Sequencer

+ BSoD integration

+ release notes integration (see workflow)

+ gameengine integration

/Ref

+ release note integration

+ gameengine integration

/Theory (same structure of Manual)

/...

/Tutorials

/feature_related (same structure of Manual)

/general_workflow

+ Books integration

+ Game Engine integration

+ FAQ integration

- ...

Extensions:<language>/<version>

/Py

/Scripts

/Howto

/CookBook (same structure of main Manual)

/Catalog (same structure of main Manual)

/Bundled ___scripts in bf-scripts trunk

/Contrib ___scripts in bf-scripts branches

/External ___scripts

in scripts-tracker but not yet in scripts-svn

on author's website

+ Game Engine integration

/Nodes

/Howto

/CookBook (same structure of main Manual)

/Drivers

/Howto

/CookBook

/API

/Blender autogenerated

/GameEngine autogenerated

/Plugins

/Textures

/Howto

/Bundled ___about plugins in bf-plugins/trunk

/Contrib ___about plugins in bf-plugins/branches

/External ___about plugins

in plugins-tracker but not yet in bf-plugins-svn

on author's website

/Sequencer

/Howto

/Bundled ___about plugins in bf-plugins/trunk

/Contrib ___about plugins in bf-plugins/branches

/External ___about plugins

in plugins-tracker but not yet in bf-plugins-svn

on author's website

Dev:

/Doc

integration of CMS info and Hackers Guide

/Ref

/Requests (same structure of main Manual)

/Competitive analysis (same structure of main Manual)

/Source

/Blender (same structure of main Manual)

/Python_API (same structure of main Manual)

/Game Engine (same structure of main Manual)

/Yafraydev

/Py

/Scripts

/Bundled ___dev doc about scripts in bf-scripts trunk

/Contrib ___dev doc about scripts in bf-scripts branches

/External ___dev doc about scripts

in scripts-tracker but not yet in scripts-svn

on author's website

/Nodes (development, examples)

/Drivers (development, examples)

+ Game Engine scripts integration

/Plugins

/Textures

/Bundled ___dev doc about plugins in bf-plugins/trunk

/Contrib ___dev doc about plugins in bf-plugins/branches

/External ___dev doc about plugins

in plugins-tracker but not yet in bf-plugins-svn

on author's website

/Sequencer

/Bundled ___dev doc about plugins in bf-plugins/trunk

/Contrib ___dev doc about plugins in bf-plugins/branches

/External ___dev doc about plugins

in plugins-tracker but not yet in bf-plugins-svn

on author's website

Org:

/Foundation

/Bf-education

/Conference

/Institute

/Open-projects

/Orange (Elephant's dream)

/Peach (Big buck bunny)

/Apricot (Yo Frankie!)

- ....

Meta: /<language>

/Guidelines

/Sandbox

/Wiki_Tasks (todo list for documenters)

+ better documenter doc, I've been lost at the beginning :)

- ....

How to restructure without messing up everything :)

Namespaces as a parking for clean content

---

As stated above, if the (Main) namespace isn't used anymore (or at least during the cleaning process) we can easily trace which content has already been moved, so properly managed.

Ranking

---

• If we MOVE a lot of pages, seach engines should keep the same good ranking for the old pages, BUT we have to keep the redirect in order people can find them.
  Will the new pages have a good ranking ever? Is the redirect considered by search engines so that they can govethe new page in search results?
  
• If we COPY each page contents in a new page, this will break the ranking achieved on actual pages.
  How to solve this?
  

   <bebraw> one issue to keep in mind is the google ranking system
            (google already ranks current wiki quite well i think)
   <bebraw> is it worth the inconvenience? (thousands of extra
            clicks per day? :) )
   <bebraw> i don't know how fast something like google can update
            their ranks to new structure
<mindrones> moving page isnt the same page?
<mindrones> we can use sitemap.xml
<mindrones> I saw something like that in wikimedia doc
   <bebraw> i recall there were some issues when google ranked
            old manual better than the wiki in the past :)

Site map

See this site map extension.

Redirecting pages with a "301 redirect": DONE!

I have tried this code on my local mediawiki: it removes the "(Redirected from...)" in the breadcrumbs up in the page, and the in the url box in the browser you see the actual url of the redirected page (not the url of redirecting page) and this tells the search engines that this redirect is "permanent", so that the pagerank of the redirected page isn't affected. See http://en.wikipedia.org/wiki/HTTP_301 for technical details.

To achieve this:

• in includes/Article.php, in function "followRedirect"

return $rt;

has to become

return $rt->getFullUrl();

• in includes/Wiki.php, in function "initialize"

$output->redirect( $article );

has to become

$output->redirect( $article , "301" );

This worked on blenderwiki (thanks jesterKing :), now we have 301 redirect.

Start a new clean wiki

---

If we go for copying contents, instead of just moving it, then I'd start with a new clean wiki, in order to:

• use short urls without break bookmarks during the cleaning,
• have a clear idea of what's happening while copying things with a bot, since you can map a wiki with many less pages (it would also take much less time while parsing the wiki and generating graphs),
• let out old contents! Old content can safely remain where it is or can be copied in an "Attic:" namespace in the old wiki.

The main problem is: since I guess redirecting between 2 wikies doesn't work (#TODO check this), once you have the new wiki you break all bookmarks, so this might be unacceptable. How do others wikies do?

See also

• Actual localization rules in blender's wiki
• MediaWiki optimised for manuals

References

• useful wiki-extensions
• actual structure

External links

• mediawiki NavFrame code to collapse frames
• wikimedia redirect help:page
• 301 redirecting
• 301 redirect code for mediawiki  <-- this should work
  
• temporary 302 redirect code <-- similar to the link above
• some MediaWiki_notes