[Bf-docboard] Documentation status and upgrade proposal

[Jeffrey H]

I would say start with the most introductory chapters first, like
"starting" or "starting/interface," to establish a standard form for
writing pages.  If those are established well and the language is easy to
read, then it would be pretty easy to continue in that style for the more
advanced topics. It seems to me that "starting/interface" already has good
form and is easy to read, at least from the few pages I skimmed through.
Perhaps we should start there and see how it goes?


On Wed, May 7, 2014 at 8:46 PM, Campbell Barton <ideasman42 at gmail.com>wrote:

> On Thu, May 8, 2014 at 11:48 AM, koil . <dd4567 at hotmail.co.uk> wrote:
> > The proposal I guess is to:
> > 1: Change the webpage and format to rst.
> > 2: Also to transform the content into a different style, I presume.
> >
> > I agree with 1. So Ill try talk about 2.
> >
> > To give a good opinion on 2. first I would have to review the pages on
> the
> > proposed webpage, learn the content.
> > Then I would have to try imagine or try transform other parts of the
> blender
> > manual.
> > Only then I can give a valid opinion.
> >
> > If the developers want to change the type of content added to the
> manual, I
> > would like to see how this goes.
> > Im still yet to learn how the new content is ordered and written.
> >
> > I like the idear of Bug Report/Todo, I think this is better than old
> reviews
> > that are hard to maintain on media wiki, and dont often get updated.
> > If users can say something is wrong with the wiki, its easier then for
> > someone to add a todo, then its easier for someone to propose a fix.
> >
> > If there are less types of content, like UI Reference, Menu Reference,
> > Editing Reference.
> > I think that will be better, less to write which is already known, and
> less
> > to translate.
> > And also people can spend more time writing better content for Intros and
> > Elements.
> >
> > I havnt seen much Editing or Workflow yet in the new content, but Cycles
> > Rendering is more about Elements than Editing or Workflow.
> > Though I havnt really read much of it yet.
> >
> > For example, how would new content style apply to Animation or Rigging.
> > If its just Elements, I guess it would be well presented examples, of
> what
> > each part of the system is used for.
> > Shape Keys, Pose Lib, Inverse Kinematics, etcetera.
> >
> > The wiki manual is good fun, but I feel likes its a dead system
> sometimes.
> > Maybe it will be good reference for what to add to the new manual.
> >
> > If the above is true about the content, its a bit depressing but,
> probably
> > for the best.
> > There any many tutorials online, so a complete intro to blender manual
> will
> > probably be better than broken mix of things.
> >
> > Koilz.
>
>
> Suggest not attempt to improve docs at the same time as migrating to
> new system, runs risk of migration never getting done.
>
> First just migrate all wiki docs to new manual `as-is`.
>
> If some docs are very low quality or out of date, they could be left out.
>
> After that. organize how to improve docs themselves, perhaps focus on
> 1-2 chapters just to prove the new system works well.
>
> At that point we probably know if this is something to stick with (and
> remove wiki manual), or if for some reason its a lot worse and can't
> be improved, we scrap the migration altogether.
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>



-- 
Jeffrey "Italic_" Hoover
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20140507/308cd69c/attachment.htm