The New Wiki: Main Task
Closed, ArchivedPublic

Description

Abstract

wiki.blender.org has served Blender well for a long time, however, it also has fallen apart over the past years. In this task, we will re-define what the wiki should be and discuss new ideas. Once the project has continued more this task can be split up into sub tasks depending on where this goes.

Questions

  • What is the purpose of the wiki now that the manual is gone?

Proposal

My proposal is to completely archive the old wiki and start fresh. This will fix the issues with being on a super old MediaWIki version and also with the amount of re-amping would be easiest. Then the idea is to spit the wiki into two webpages. The first would be a second manual, this manual would be used to document developer things (see below). My proposal is to use sphinx fir this. Then the wiki would then be a "hub" to bridge the gap between users and developers and other users.

Things to include in this new manual

  • Code documentation
    • code layout
  • Building Blender
  • tools for developing blender
    • Git
    • SVN

ect.

Things to include in the "hub"

  • Addon documentation
  • User Pages
  • Release logs
  • Link to other areas of blender
    • Blender Foundation
      • Developer areas
        • developer.blender.org
        • developer documentation (see above)
      • Users areas
        • Blender.org
        • cloud.blender.org
    • Blender Institute
      • project going on at the institute
    • Blender Communities

Must's

  • No wiki version. The old wiki which had support for going back and looking at old version of Blender. This was one of the pitfalls of the old wiki, when pages were not updated but the pages about them were.
  • A new theme. The old theme is outdated and very old looking. The new theme should only have one side bar.

Details

Type
Design
Aaron Carlisle (Blendify) triaged this task as Normal priority.Feb 25 2016, 6:55 PM
Aaron Carlisle (Blendify) changed Type from Bug to Design.

@Aaron Carlisle (Blendify), tasks like this rely on having people to perform the migration/updates.

Informally we've discussed the possibility of moving to a new wiki (with the possibility of migrating only relevant content).

However unless current admins have time to do a migration, not sure its useful to keep this task open.


As for the proposal, agree the wiki versioning hasn't worked will for us.

Though I'm not convinced moving developer documentation away from the wiki is really needed.
While personally I'd be happy with this change, this is one area where these wiki has worked well for us.

For developer docs it would make sense to use the wiki built into phabricator (example). It's easy enough to enable on this install, but it's a massive task to migrate all the content.

That sounds like a good solution. I wonder if there is vision control capability.

BTW a quick mock up of using Sphinx: https://drive.google.com/folderview?id=0B6dOW1HeIPTHelMyM2NOU1dISk0&usp=sharing

The phabricator wiki does have a version history similar to mediawiki. It would be nice to have a single website, with one acount, one place to track development related activity, easy linking to tasks and commits, and one syntax for commenting in tickets and writing docs.

But the current wiki does work and switching to something else doesn't solve any major problems that we are having, as far as I know. So it's a bit difficult to justify the effort.

I would strongly oppose going the same route as with user docs. A git/commit based system makes it a very unfriendly system for people to help out. It "looks good", that's all we have now. The current manual project is still struggling to find active contributors, for reasons.

Same usability issues were added to wiki btw. Structure (navigation, namespaces etc) was added over usability. That's a bad convention. People come first, always. Easy access and immediate updating is the strength of wikis, and we can simply keep using that.

Where are the tech doc authors? I used to be one of the top contributors to wiki and I have no problem with it whatsoever. Just update it, fix the skin, or simplify the usage of it.

From replies on the mailing list

http://lists.blender.org/pipermail/bf-committers/2016-February/046828.html

Conclusion is to keep using a wiki, (upgrade our existing wiki or migrate to new wiki - either way we would keep roughly what we have now).

I would be willing to put more than a little time into it if you guys need someone who will focus just on that.