[Bf-docboard] wiki refactor: help cataloguing UI images!

[Mike Belanger]

Forgive my naivete towards this kind of thing, but I'm confused.
If the people in the wiki channel themselves tell you MediaWiki isn't  
good for software documentation, should we switch?
It sounds like swaths of articles and images are going to be re-done  
anyways, not to mention entirely new tutorials are
going to be written.

Right now, 2.5 stands on crossroads - and there's fervent discussion  
on which way to go.  It sounds
like at any rate, a full re-factor won't happen until the end of 2009,  
or even later.   I wonder
if we too should have an eye on the future of the documentation, and  
make some changes, even
if it takes longer.

I'm going to finish cataloging images today, and gladly help out with  
the wiki.
But I'm wondering if any of you have thought about switching to  
another CMS system.

A lot of people here praise Drupal.  What do you guys think?


http://www.empowerthyself.com/mediawikiisobsolete







On 22-Mar-09, at 5:21 AM, mindrones wrote:

>
> Hi,
>
> --- On Sun, 3/22/09, Tobias Regenbrecht <regenbrecht at gmx.net> wrote:
>
>> With all your categorizing and templating and sorting and
>> the like, you won't
>> get a page more to be written and finished.
>
> I don't agree, all this stuff about categorizing images is for  
> simplicity.
>
> Mikahl is going to finish the job, so now we can clearly see what's  
> missing and what's ok, have a look here
> http://wiki.blender.org/index.php/User:Mindrones/Reference/UI_elements
> (Tuesday I'll update it with all elements, I do the wikitext with a  
> pyscript I don't have here at the moment :)
>
> I'll link that page to the style guide after the clean up, so that  
> it will be a resource for writers.
> I'll do also a page with non-categorized images, so that we can keep  
> this up to date.
>
> The idea of templating comes from some discussion about automating  
> screenshot creation in 2.5x: a Blender "demon" on a server can  
> create screenshots and it will just a matter of update templates  
> with a bot.
>
> Once this will be set, writers will just have to consult a page with  
> available screenshots in a page similar to
> http://wiki.blender.org/index.php/User:Mindrones/Reference/UI_elements
>
> Think about this as an experiment for some future simplification :)
>
>
>> -> keep it as simple as possible for others to contribute.
>
> I don't see the problem if things will be well explained in the  
> style guide.
>
> If people will ignore the style guide at least it will be easy to  
> update things on the way.
>
>
>> -> make it easy to share the content with other places
>> and keep the license as
>> open as possible.
>
> What's the problem with the license?
>
>
>> -> keep the structure flat so that you can rearrange the
>> table of contents
>> without moving the pages.
>
> People in wikipedia channel just told me plain and simple that wiki  
> is not a  good tools for manuals, because of its flatness (they said  
> "just use a CMS"), so we should take the best from wiki with some  
> effort for structuring.
>
> I don't see problems in moving pages. Giving a structure serves to  
> easily find things out of the structure itself, so it's easy to keep  
> things ordered.
>
> Three months ago there were a lot of old/incomplete/doubled pages  
> which required some thinking to know what to do about. That was too  
> much confusing.
>
>
>> -> most images can be used only once, because they show
>> something specific. If
>> they show something specific it shouldn't be necessary to
>> describe them
>> twice, so they are used at a unique place. This may be
>> different for
>> tutorials though.
>
> You can still use the images as you do now if you prefer.
> As said before, better to stick to a style guide though.
>
>
>> -> keep old pages intact, including the images. At least
>> the author of the
>> page needs to be honored, don't throw his work away he will
>> never come back.
>
>
> After we'll have things refactored, we will be able to copy the  
> manual to Doc:2.48/Manual and keep updating Doc:Manual, so old  
> images will still be in Doc:2.48/Manual, and we'll be able to update  
> new ones.
>
>
>> -> never ever offend an author by ripping a page apart
>> he has written. The
>> authors are the most valuable good you have, honor their
>> work they do it
>> voluntarily.
>
> It's not a personal thing of course. It's just a practical thing.
> Keeping an old page just for the sake of not offending someone makes  
> the manual old very soon.
>
> IMO we should think to readers first. One of the main reason I  
> started this is because I was frustrated sometimes reading the wiki,  
> I just imagined all the other ones like me and decided to give my  
> contribution.
>
> Hope this can help to make things more clear :)
>
> Regards,
> Luca
>
>
> _____________
>
> http://www.mindrones.com
>
>
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard