[Bf-docboard] Suggestions to improve wiki useability

Fri Jan 11 19:38:36 CET 2013

 I still don't know why Houdini documentation is
considered sometimes ''the best'' documentation.

 I don't think so...

 I know that there is no way to avoid such critics, but, in fact
 our documentation project (in a sense of completion)
surpasses the Houdini documentation project

 Houdini documentation is guided to ask support for a teacher first
 ours is guided for people whose wanna read the manual and
start using Blender

 But I agree, the lines are mixed in most of our manual

 I mean, technical documentation is sometimes mixed with tutorials.
 The difference should be technical examples from tutorial examples

 This is hard to achieve in some situations, but it's possible.
 I still believe that we have a good documentation project
at our hands, but needing a format normalization and updates

I also have tried to see what happens when we try to
export Houdini or Autodesk manuals to PDF formats.

No way !

We are at IRC #blenderwiki everyday !  ;)

Ivan Paulos Tomé
Greylica - My brain is grey like yours !

2013/1/11 <bf-docboard-request at blender.org>

> Send Bf-docboard mailing list submissions to
>         bf-docboard at blender.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         http://lists.blender.org/mailman/listinfo/bf-docboard
> or, via email, send a message with subject or body 'help' to
>         bf-docboard-request at blender.org
>
> You can reach the person managing the list at
>         bf-docboard-owner at blender.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Bf-docboard digest..."
>
>
> Today's Topics:
>
>    1. Suggestions to improve wiki useability (Cal McGaugh)
>    2. Re: Suggestions to improve wiki useability (Cal McGaugh)
>    3. Re: Suggestions to improve wiki useability (Jared Reisweber)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Thu, 10 Jan 2013 21:05:49 -0500 (EST)
> From: Cal McGaugh <cal at cal3d.com>
> Subject: [Bf-docboard] Suggestions to improve wiki useability
> To: bf-docboard at blender.org
> Message-ID:
>         <
> 265802886.900634.1357869949630.JavaMail.open-xchange at email.1and1.com>
> Content-Type: text/plain; charset="utf-8"
>
> Hi Keston,
>
>  As I began to look closely at the current pages that Jim assigned me to
> edit
> (Sketching) ,  I realized why I hadn't been using the
> wiki more in the past.....I find the current formatting very distracting,
> and
> difficult to extract & understand
> the relevant info of the page.
>
> So I took the liberty to remove most of the template code to see how it
> would
> look.
> e.g. "Description",  "Options", "Usage" etc,  the in-line button images,
> numbering each heading (1.2.1.2 etc),
> and the large darker boxes (at least in the Naiad skin version).
>
> They are un-necessary, and in fact, counter-productive to useability, imho.
>
> I showed this to Jim Tucker and he seemed to think it was an improvement.
>
> Here is the current version of this page using templates
>
> http://wiki.blender.org/index.php/Doc:2.6/Manual/3D_interaction/Sketching/Drawing
>
> And this is the one that I edited by removing most of the templates.
> http://wiki.blender.org/index.php/User:Megacal
>
> I kept the relevant headings with their font size & bolding, also bulleted
> points. The rest was redundant and distracting......at least for me, and
> I think for many others as well.
>
> Not only would it make the pages easier to use, it makes it easier to
> create &
> edit if we aren't constrained to use
> the templates. This does not mean that pages would become
> inconsistant.....the
> style should always be consistant.
>
> "The main purpose of wiki maintenance is to ensure that the content of
> each page
> provides the user with a clear,
> concise and up-to-date description of the Blender function in the current
> version. Over and above this, the page
> should conform with the User Manual context (see below) so that we keep a
> uniform User Manual layout." ....should always be the standard.
>
> I'd also like to propose doing a user poll at Blenderartists.org (if you
> think
> it would be productive and help to improve useability)  to ask if:
>
> * Do you use the wiki?
> * How often % vs videos and/or books?
> * Do you have any suggestions for improving it so you would use it more?
> * What do you think of this page vs this page?  (the current version vs my
> proposed version).
> BTW,  I didn't realize until after I had started the editing that Fade had
> already started working on the Sketching pages.......I tried to contact
> him/her
> to see if they wanted to finish
> alone, with my help, or would want me to finish the pages....no reply , so
> am
> not publishing the pages yet, though did submit it to Jim for review.
>
> There's a good primer on website useability, Don't Make Me Think
> <
> http://www.amazon.com/Dont-Make-Me-Think-Usability/dp/0321344758/ref=sr_1_1?ie=UTF8&qid=1357869508&sr=8-1&keywords=book+don%27t+make+me+think
> >
> , and I believe the same idea makes sense for the wiki, too.
>
> I was going to post this at the doc-board, but wanted to get your Ok
> first. It
> may have even already been proposed years ago.....I'm still wet behind the
> ears
> here & in Blender.
>
> If you do think it's worth pursuing, I'd even be willing to limit my
> editing to
> cleaning up all the current pages.......it would be a good project to keep
> me
> off the streets. =)
>
> Whatever you think is best, I'll abide with it.
>
> Thanks,
> Cal
>
>
>
>
>
>
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL:
> http://lists.blender.org/pipermail/bf-docboard/attachments/20130110/f906c9a2/attachment.html
>
> ------------------------------
>
> Message: 2
> Date: Thu, 10 Jan 2013 21:11:19 -0500 (EST)
> From: Cal McGaugh <cal at cal3d.com>
> Subject: Re: [Bf-docboard] Suggestions to improve wiki useability
> To: bf-docboard at blender.org
> Message-ID:
>         <
> 819456442.900796.1357870279158.JavaMail.open-xchange at email.1and1.com>
> Content-Type: text/plain; charset="utf-8"
>
> Well this is embarrassing......meant it only for Keston for now......my
> apologies.
>
> But would appreciate any feedback from the group as well.
>
> Thanks,
> Cal McGaugh (noob)
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL:
> http://lists.blender.org/pipermail/bf-docboard/attachments/20130110/5ff0457f/attachment-0001.htm
>
> ------------------------------
>
> Message: 3
> Date: Thu, 10 Jan 2013 22:54:43 -0800
> From: Jared Reisweber <jaredr122 at gmail.com>
> Subject: Re: [Bf-docboard] Suggestions to improve wiki useability
> To: Cal McGaugh <cal at cal3d.com>,        Blender Documentation Project
>         <bf-docboard at blender.org>
> Message-ID:
>         <
> CAJgraRReQ3qX57HxF8_BNn-WQ_7j8D24ozcL2QZH8yhLgF68dg at mail.gmail.com>
> Content-Type: text/plain; charset="iso-8859-1"
>
> I'd like to chime in, as an editor who has seen a lot of wiki pages,
> I don't completely agree with your level of simplification, but I agree
> that some of the wiki formatting is distracting and hard to read. I think
> the bigger problem is the inconsistency of the use of formatting, which
> stems from the fact that there is no real standard for the way pages are
> formatted (for example, when to use bullets, or what should be bold, or
> when to make a sub-heading). I think we should decide on some standards
> that would encompass anything that would be in the manual.
>
> The second problem is the actual formatting. It is hard to read. I had
> suggested to Kesten about the use of indentation, which is fairy common in
> documentation that I've seen. I also am in favor of color formatting(see
> Autodesk's documentation). I think in addition to standardizing formatting,
> we need to revise the formatting style so that it makes pages easier to
> read and understand. I'm thinking these things should be discussed
> thoroughly before going and changing all the manual pages.
>
> Here are some examples from Houdini's documentation, which is easy to read:
>
> http://www.sidefx.com/docs/houdini11.0/model/polys
> http://www.sidefx.com/docs/houdini11.0/light/shadows
>
>
>
> On Thu, Jan 10, 2013 at 6:11 PM, Cal McGaugh <cal at cal3d.com> wrote:
>
> > **
> >  Well this is embarrassing......meant it only for Keston for now......my
> > apologies.
> >
> >  But would appreciate any feedback from the group as well.
> >
> >  Thanks,
> >  Cal McGaugh (noob)
> >
> > _______________________________________________
> > Bf-docboard mailing list
> > Bf-docboard at blender.org
> > http://lists.blender.org/mailman/listinfo/bf-docboard
> >
> >
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL:
> http://lists.blender.org/pipermail/bf-docboard/attachments/20130110/f0d38711/attachment-0001.htm
>
> ------------------------------
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>
>
> End of Bf-docboard Digest, Vol 95, Issue 5
> ******************************************
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20130111/ecf1f137/attachment.htm 