[Bf-docboard] 2.5 Wiki Changes
mindrones
mindrones at gmail.com
Mon Nov 7 13:44:31 CET 2011
Hi all,
On 11/07/2011 03:01 AM, Jared Reisweber wrote:
> I never meant to cause so much stress for the documentation development.
> I saw that the 2.5 index had been changed back to the pages that I put
> there, so I assumed it was okay to go forward with adding the missing
> content. I think this fact is going to add confusion to other wiki
> editors as well.
A wiki writer should follow the guidelines.
If he's among those that want to intend to add a lot of pages, then he
should follow and discuss here.
http://wiki.blender.org/index.php/Meta:Guides/Writer_Guide#Major_Edits
I've sent an email here about the review before the 2.6 move.
http://lists.blender.org/pipermail/bf-docboard/2011-November/003772.html
> Regarding your comment about filling the wiki with 2.4 content, I have
> been carefully going through the 2.4 content before porting it to
> corresponding 2.5 pages and editing all content to reflect its relevance
> to 2.5, except for images, which I have been documenting
this is why one should work in the sandbox
, along with
> other significant changes that are needed, in my public spreadsheet:
> Blender Wiki Content
> <https://docs.google.com/spreadsheet/ccc?key=0AgUiaPsPYcKpdElpc2V3S1JIb21kUTNMT0YzTTJ2X3c&hl=en_US&pli=1#gid=0>.
this is not the workflow stated in the guidelines.
For such radical changes, you have to look for some review.
http://wiki.blender.org/index.php/Meta:Guides/Writer_Guide#Major_Edits
It's not that if it is in the public spreadsheet you're ok to do massive
changes to a public wiki without caring about communication with others.
--
Take Bastien for example. In the recent past he has rewritten and
reshuffled 5 very big chapters in this wiki.
When he did the modeling and lighting chapters, which were mostly
reshuffling + rewriting parts, he made the changes in the sandbox, got a
review from me and he moved.
When he rewritten the Animation chapter and written anew the Rigging
chapter:
- he has presented a plan in the wiki itself in the sandbox, much like
your sandbox proposal, very, very detailed.
- he got review from Roger, Mikahl and me.
- he did the work in sandbox pages
- got a review from me and mikahl of the real pages
- then we moved them in the real manual
After he's been following the rules (that only means don't act like you
don't need any review from anyone, which is silly), and has shown very
good quality chapters, he has gained our trust.
Even if he could write directly in the manual, as you are doing now, the
last time he wanted to do a chapter in 2.5 I just asked to discuss the
chapter index, and he simply agreed, because it is normal.
It's called "peer-reviewing".
Working with others is normal, and in a project like this I'd say it is
even vital.
If you don't intend to do it, that's not my problem honestly.
Note that it doesn't have to be me reviewing. On the contrary I'd like
to have more trusted people, so that I have not to do it....
> I don't like to come across as cocky, but I have put many hours into
> adding content to this wiki, that users have been complaining about for
> a while. I have been carefully respecting the wiki formatting guidelines
> and even correcting mistakes made by other users. Everything I have done
> has been to improve the user experience.
That's much appreaciated.
> Out of the 454 or so wiki
> pages, i've only changed page links for about 70 of them (see the second
> sheet in my Google doc), so I don't know what you mean about not
> following the 2.4 structure "at all."
70!
Man, that's what I'm saying: you have been deliberately doing all this
without waiting for a review.
We had a discussion back in June, and I've been seeing you going on in
the wiki following your (OWN) plans. I didn't like it much.
You might write super quality content, but seeing you acting as you
don't need peer-review is scary, because you give the (IMHO bad) example
to others that will want to join and start working in wiki: they will
think "if Jared did it, I can do it too".
At that point probably Jared will be the wiki admin (because mindrones
left :) and will start discussing with all the people that simply don't
want to follow 2 rules, and maybe Jared will understand what that
mindrones was saying back then :)
The only thing Jared could do at that point is replying mails to people
that will ignore them, or ban those people: in both cases I don't see a
good workflow there.
If you don't like the current guidelines, feel free to propose new ones.
But anarchy is not an option, or at least not one that I'm willing to
accept.
> Honestly it really wasn't clear
> when I started that the link structure needed to be the same, but I do
> see now the problems it is causing.
That 's not true. We had a discussion about it, here.
And there were a banner in 2.5, in orange, stating that.
It's time to restore that I think.
> I completely understand your point
> in regards to having a consistent wiki structure, and I am more than
> willing to put the time in to transfer content from the pages I created
> to proper pages for the 2.5 manual when it is agreed upon. That would
> only take me a few days to do.
Please don't do it yourself. I'd prefer Bastien and I do that.
> I will hold off on adding more pages until the structure is agreed upon.
> I'm just curious, and in no way mean to sound sarcastic,
There would be no reason for you to be sarcastic indeed.
We all are working very hard.
> but why is it
> so vital that users need be able switch between documentation pages for
> different versions of Blender. Personally I don't see the major benefit
> of having that functionality, but maybe I'm missing something. I can't
> see why someone viewing documentation for, say a 2.5 page, would
> suddenly need to view its 2.4 or 2.6 counterpart.
1) On 11/07/2011 04:17 AM, Jaagup Irve wrote:
> The main function would be to serve people from search who dont arrive
> at their version, I guess.
Exactly.
Since 2.4 pages have higher ranking than 2.5 pages, people might find a
2.4 and desire to see the newer version of it.
2) Most important, the 2.5 version has not been reviewed yet, hence I'm
not sure it's 100% quality. Don't assume that it's final.
Hence:
2a) if someone can't solve his doubt in a certain 2.5 pages it is more
than logic to desire to see the 2.4 docs, in case they were more
complete. --> I need the 2.4 version
2b) if I find 2.4 screenshots in a 2.5 I think, "yeah ok, so what's the
difference? Maybe they did a copypaste and added some edit, let me
check" --> I need the 2.4 version
3) Search engines use the information that page A is linked to B. If
there is no correspondence, you lose a chance to help search engines
understand your structure.
4) Blender has not changes so drastically after all, apart from
animation and GUI. Hence the manual structure doesn't need to change at
all costs: it just needs to change where it's not possible to do otherwise.
In any case, the changes have to be discussed, here or in #blenderwiki
and reported here.
5) There are people still using 2.4 out there. At some point they do, or
they will do the switch. It helps moving from a manual you know to
another that is very similar. It makes no sense to me to change thre
structure drastically for no benefits, forcing people to scroll chapters
to see what's changed.
Regards,
Luca
>
> -Jared
>
>
> On Sun, Nov 6, 2011 at 3:47 PM, mindrones <mindrones at gmail.com
> <mailto:mindrones at gmail.com>> wrote:
>
> Hi Jared,
>
> right now we're doing some review of the 2.5 manual and, sadly, we're
> finding out that the 2.4 structure has not been respected at all.
>
> Even tonight I see that you are keeping adding pages in the animation
> section without following the 2.4 structure:
> http://wiki.blender.org/index.php/Doc:2.5/Manual/Animation/Drivers
>
> This is making our review much worse than needed, honestly. It has been
> stated for 2 years (in the old banner) to use the sandbox or follow the
> 2.4 structure, but apart from one proposal page
> http://wiki.blender.org/index.php/Meta:Sandbox/Doc:2.5/Manual_Proposal
> you have simply kept working in the Doc:2.5/Manual not following the 2.4
> structure...
>
> Currently many chapters won't crosslink with the headers-menu for this
> reason. I think in the current skin you have seen what I was meaning
> with crosslinking: I can't understand why you keep not following the 2.4
> structure at all..
>
> Also, there are many pages with 2.4 screenshots, the driver page being
> an example: please don't do that.
>
> It has no sense to just fill the gaps with 2.4 content, because many
> pages will appear as ready, forcing us to read the whole manual to spot
> the problems.
>
>
> The fact that we use a wiki doesn't mean that we don't follow some
> rules; writing in a wiki means trusting that everyone follows the same
> rules, otherwise, as this review has shown, it quickly becomes as mess,
> which means bad user experience, and massive work for us to review :/
>
>
> I would kindly ask you to work in the sandbox, and not in
> Doc:2.5/Manual, for a while, until we sort out a bit the correspondence
> among pages 2.4 -> 2.5, in order to make some order in the structure.
>
> If you could talk more with everyone, your hard work would be much more
> useful, and you would avoid the risk to see your work removed or heavily
> edited, so best we discuss here or at #blenderwiki.
>
> Thanks,
> Luca
>
>
>
> On 06/13/2011 11:10 PM, Jared Reisweber wrote:
> > I totally understand your points. That's why I emailed the docboard. I
> > felt this needed to be discussed. If some one came and made changes, I
> > would be okay if they were logical, but yeah, if they were drastic,
> > there should be some discussion.
> >
> > I see what you are saying about the order of materials, textures and
> > rigging animation. I had felt that lighting and rendering should maybe
> > go together, then I put materials and textures with those. I was
> looking
> > at Maya's help docs, and they have
> shading/textures/lighting/render all
> > grouped under a rendering section. But I haven't looked at docs
> for any
> > other programs. Of course, I guess the order of chapters is probably
> > less important the order of the contents in the chapters.
> >
> > I think the sections that need the most organizational
> consideration are
> > modeling, animation, and rendering. I personally had felt that the
> mesh
> > tool sections were too awkwardly separated, so I divided them into
> four
> > new sections: transform/deform, add and divide, merge/remove, and
> > separate. It also seemed to me that the Object section should go
> before
> > section on object manipulation, and objects encompass non-editable
> > things as well, that don't really belong in the modeling section.
> >
> > For the rendering section, I reordered the pages to: using the camera,
> > setting the rendering quality, and then options for outputting
> renders.
> > The animation section was difficult. I removed all pages referring to
> > IPOs, and tried grouping pages by their editor window.
> >
> > How is the cross-linking going to work? Will the 2.4 pages just have
> > links to their respective 2.5 page, or is it something more
> complicated?
> >
> >
> > On Mon, Jun 13, 2011 at 3:37 AM, mindrones <mindrones at gmail.com
> <mailto:mindrones at gmail.com>
> > <mailto:mindrones at gmail.com <mailto:mindrones at gmail.com>>> wrote:
> >
> > Hi Jared,
> >
> > I think it's ok if you keep working in the sandbox and when
> you think
> > you are done you add some little text below each chapter to
> explain what
> > you have done and why.
> >
> > For example roght now the 2.5 manual has materials and
> textures after
> > rigging and the animation. That's disputable. IMO usually
> people start
> > with static scenes, adding materials (colors, you know :) and
> after some
> > expertise they start to rig and add constraints etc.
> > I have to admit that I've been thinking at that approach many
> times, but
> > I'm convinced that this kind of changes have to be discussed here.
> >
> > If you want to merge pages or write new ones, again make new
> pages in
> > the sandbox.
> >
> > Bastien has done the same months ago and though it's been
> hard, it has
> > given its fruits and now the manual is more mature than
> before, at least
> > in my opinion.
> >
> > If we really let the manual open for such changes, then go
> figure if
> > suddenly a "Jared2" comes and start to change all your changes
> again,
> > what would you think?
> >
> > Probably you would say, hey let's discuss first! :)
> >
> > Laters,
> > Luca
> >
> >
> >
> >
> >
> > On 06/13/2011 06:54 AM, Jared Reisweber wrote:
> > > Okay. Yeah, that's what I was afraid of. I got a little
> excited. I'll
> > > copy over the current state of the manual to Meta:Sandbox,
> then revert
> > > the manual back to look like the Doc:Manual/earlier
> Doc:2.5/Manual
> > index.
> > >
> > > The sandbox link is:
> > >
> http://wiki.blender.org/index.php/Meta:Sandbox/Doc:2.5/Manual_Proposal
> > >
> > > The 2.5 index had considerable differences from the 2.4
> index already
> > > when I started, so its hard to judge what I should put back and
> > > add/remove. I changed it back a little bit. Do you want me
> to straight
> > > up just revert it back to the version before I messed with
> it, or make
> > > it look like the 2.4 index? Bleh, now I'm really confused. heh.
> > >
> > > Some of the changes I made were necessary, as many topics
> were missing
> > > completely, and many 2.5 features are very different from
> their 2.4
> > > counterparts, such as the animation system.
> > >
> > > Other changes were made to consolidate very short pages
> together.
> > Also,
> > > some features from 2.4 were rearranged in 2.5's interface,
> lending
> > > themselves to be grouped differently in the manual. For example,
> > > consider the Output Panel, and the Format Panel in 2.4's render
> > > settings. These have changed considerably in 2.5, as far as
> > > organization. The manual should reflect this new grouping and
> > workflow,
> > > which why many of my changes seemed logical.
> > >
> > > The pages are still there for the most part, they just have been
> > grouped
> > > a little differently, and some have been added. It probably
> looks more
> > > changed than it actually is. Most of the changes have more
> to do with
> > > the usability of manual itself than the changes to Blender
> in 2.5,
> > in my
> > > opinion.
> > >
> > > On Sun, Jun 12, 2011 at 10:22 PM, mindrones
> <mindrones at gmail.com <mailto:mindrones at gmail.com>
> > <mailto:mindrones at gmail.com <mailto:mindrones at gmail.com>>
> > > <mailto:mindrones at gmail.com <mailto:mindrones at gmail.com>
> <mailto:mindrones at gmail.com <mailto:mindrones at gmail.com>>>> wrote:
> > >
> > > Hey Jared,
> > >
> > > I've been looking with more attention at the 2.5 manual
> index
> > and WOW..
> > > I have to say that you are making it diverging quite a lot
> > from the
> > > official manual index...
> > >
> > > As stated in the orange banner up there, the idea is to
> update the
> > > official manual pages for 2.5 changes, while what you are
> > doing is too
> > > much drastic in my opinion.
> > >
> > > Personally I'd prefer you to revert your changes in
> > Doc:2.5/Manual and
> > > prepare a sandbox page where you propose these structural
> > changes here,
> > > so that everybody can discuss. Otherwise crosslinking
> will be
> > impossible
> > > and really it will be very hard to compare the changes
> against 2.4
> > > manual.
> > >
> > > I don't really think blender 2.5 is so much different
> from 2.4 to
> > > justify all these structural changes in the manual.
> > >
> > >
> > > Regards,
> > > Luca
> > >
> > > _____________________________
> > >
> > > http://www.mindrones.com
> > > _______________________________________________
> > > Bf-docboard mailing list
> > > Bf-docboard at blender.org <mailto:Bf-docboard at blender.org>
> <mailto:Bf-docboard at blender.org <mailto:Bf-docboard at blender.org>>
> > <mailto:Bf-docboard at blender.org
> <mailto:Bf-docboard at blender.org> <mailto:Bf-docboard at blender.org
> <mailto:Bf-docboard at blender.org>>>
> > > http://lists.blender.org/mailman/listinfo/bf-docboard
> > >
> > >
> > >
> > >
> > > _______________________________________________
> > > Bf-docboard mailing list
> > > Bf-docboard at blender.org <mailto:Bf-docboard at blender.org>
> <mailto:Bf-docboard at blender.org <mailto:Bf-docboard at blender.org>>
> > > http://lists.blender.org/mailman/listinfo/bf-docboard
> >
> >
> > --
> >
> > Regards,
> > Luca
> >
> > _____________________________
> >
> > http://www.mindrones.com
> > _______________________________________________
> > Bf-docboard mailing list
> > Bf-docboard at blender.org <mailto:Bf-docboard at blender.org>
> <mailto:Bf-docboard at blender.org <mailto:Bf-docboard at blender.org>>
> > http://lists.blender.org/mailman/listinfo/bf-docboard
> >
> >
> >
> >
> > _______________________________________________
> > Bf-docboard mailing list
> > Bf-docboard at blender.org <mailto:Bf-docboard at blender.org>
> > http://lists.blender.org/mailman/listinfo/bf-docboard
>
>
> --
>
> Regards,
> Luca
>
> _____________________________
>
> http://wiki.blender.org/index.php/User:Mindrones
> http://www.mindrones.com
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org <mailto:Bf-docboard at blender.org>
> http://lists.blender.org/mailman/listinfo/bf-docboard
>
>
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
--
Regards,
Luca
_____________________________
http://wiki.blender.org/index.php/User:Mindrones
http://www.mindrones.com
More information about the Bf-docboard
mailing list