[Bsod-mentors] Official Start

Mon Jun 19 19:26:27 CEST 2006

Hi BSoD'ers,

Sorry I'm a day late, but getting everything organised, especially the wiki
stuff has been a bigger job than I imagined (sad excuse I know!).

Firstly, a few notes on wiki editing -

a ) We have created some base style guidelines which you can check out at
http://mediawiki.blender.org/index.php/Sod_Template
These must be adhered to, and I'm going to reitereate most of them here
anyways.

b ) SideNote usage - As I mentioned in an earlier email, I'm concerned about
writers going off on tangents and disrupting information
flow.  The original template for a Note type thing met with a resounding
'no', however this one is a little more wiki like, and takes into
account all of the remarks made in the last email.  You can take a look at
the new version on the template link above.  I really want to
see it get used if you want to make a side note (though don't use it if you
dont need to of course), say for example a little exercise the
user can do with just a few steps could go nicely into one of those boxes,
and afaik images should work in it too, though make sure
they are small.

Ok to use the note is esay, in your text where you want it, type : {{SideNote
| [left or right] | title | main body}}

c ) All your pages must have the BSoD header at the top, which can be
inserted by putting : {{BSoD/navigator | 2.41}} at the top before
anything else.

d ) Wiki automagically creates contents pages based on your headings, so
please make sure you keep everything under headings and
sub headings so that the wiki creates nice contents pages for your project.

e ) With the above said, we dont want all your documentation on one
page....that would be insane.  So we want you to consider how you
want to seperate content onto multiple pages, and discuss it with your
mentors, then we can discuss with you the best way to set up your
wiki structure to support it.   So over the coming days, we'd like to see a
small doc from each of you detailing how you will seperate
your project into multiple pages (this doesnt have to stop you starting
work)

f ) All screenshots must be created with the standard Blender Default theme,
no funky green themes (yes you know who you are!)
Remember Blender has its own screen dump facilities if you need whole
windows, otherwise if you're on Win you can use Winsnap
which allows you to selected the area to capture.  Dunno about loonix
sorry.  Also make sure that your screenshots only show whats
necessary.  With regards to overlays, if you must draw onto screenshots,
please use solid black, #000000 and don't put text.  If you
want to put a reference to something use a solid black circle with a white
number on it eg (1) then have a caption under the image with
eg (1) Shadow Only button.  The number should be White #FFFFFF, Arial font,
size 14 bold, and the captions should only be basic,
reference the reference manual if you need detailed explanation, or put more
details in the body of your text.

g ) Make sure your images do not change extend outside the borders of the
page layout, you can have clickable previews, which you
can look at how to do in the template I linked to above.  On that note, keep
all images as JPG's please (not too heavily compressed)
and upload them to the wiki please, no external hosting..

h ) make sure you use the hotkey templates, which you can check on the
editing help pages.  That way when Matt comes in to
do his job, it will be a matter of just updating the template, and we
suddenly get nice hotkeys :)

Finally, make sure nothing extends outside the borders of the wiki layout.
No images, no tables, no tables of images etc :) and please
please have a good read over
http://mediawiki.blender.org/index.php/Meta/Style_Guide even if you have
already.

I know that all of that sounds exceptionally picky, and I'm sorry for that,
but we really need to get everything uniform and looking good,
after all this will be official Blender documentation, and may decide
whether we get to have another SoD after this one.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Ok now questions and answers from emails I have so far:

Well, we do have a month now. This page shows that we were originally
> going to be give a week:
> http://mediawiki.blender.org/index.php/User:Timmeh/BSOD_Guidelines,
> but I guess that has changed. Which is good, because I have a lot of
> things going right now and I need that extra time.
>
> Also, am I supposed to write above or below your text, or am I
> supposed to delete your text?
>

You should do nothing of the kind.   If you go to the start page of the
wiki, http://mediawiki.blender.org
there is a link, under Core Documentation, to Blender Summer of Docs, then
find your name and proposal
and click on the heading, this will take you to your project's home page.
This will be where your introduction
is located, as well as links to the other parts of your docs, which is why
it's important for you to think about
how you will seperate your project into different parts and pages, you can
write on here until you have discussed
content seperation with your mentor, when they will help you set up the
structure to support the remaining pages
of your docs.

We are still waiting for the mentors to contact us, right?
>
> This seems like a question for a BSoD mentor, but I'll put it here
> anyway: About 10-20% of the material I proposed to document has
> already been covered in detail. Namely, the intro to armatures:
> http://mediawiki.blender.org/index.php/Manual/PartIX/The_Armature_Object2
> http://mediawiki.blender.org/index.php/Manual/PartIX/The_Armature_Object
>
> Do I skip this section? Do I rewrite it?
>
> I'm trying to find the guidelines that say what margin sizes are to be
> used to determine the number of pages of our writings. I remember the
> text size is 10.
>

Yes you are still waiting, and I'm going to tell you later in this mail who
your mentors are.

Hrm regarding content reduncancy, that's a tough topic, and the conclusion
I've come to is that you should rewrite it
if it is fundamental to the topic, so Introductions should definitely be
rewritten.  The main reason I have for this, is that
these are really seperate from the rest of the documentation, things like
tools and reference material should go
into the reference section and linked, but everything else you should
document yourself, regardless of content
redundancy.  Another reason is that I expect your projects to produce better
content than exists already, since they
are paid projects.

I imagine some of these tutorials have the potential to be so
> hyperlinked they're almost all blue:
>
> "[Select] the [vertices] using [edge loop select] and [extrude] along
> the [x axis]."
>
> Now, I know as an author it would get tedious to link every other word.
>  But to be consistent, should we link everything we can?  I don't know.
>  Maybe it's worth thinking about just what commands we should link and
> how often we should link them.
>
> I think it would be useful to have a running list of commands for the
> authors to refer to.  An example: Say I want to link to edge loop select
> in my tutorial.  Do I use [edge loop selection], [edge loop tool], or
> [edge loop select]?  A master list would help because I could check that
> and see that there's a page (or at least a stub) on the wiki for [edge
> loop select] . . . so that's the link I would use.  Such a master list
> could also double as an index for the reference section of the manual.
> Just some thoughts.
>
>
Mat's reply to this email was perfect and exactly on right track, please
refer to it.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Ok now your mentors :

Michael and Felipe, your mentor is etrp9, Eugene Reilly,
etr9j at blendernation.com

Rob and Mal, your mentor is macouno, Dolf J. Veenvliet, info at macouno.com

Ryan, Guillermo and Willian, your mentor is spiderworm, David Millet,
david at tellim.com

which of course means,

Stephen, Colin and Fred, your mentor is me, timmeh, Timothy Wakeham,
tim.wakeham at gmail.com

Now, I've given personal emails out (please don't abuse them), however most
of your emails should go to the mailing list
where your mentor will answer them, if you wish to contact your mentor
privately for some reason, they are there.

So I think we are finally ready to get your projects underway, remember that
we're here to help, so if you need help, ask!  I imagine we
will have some issues to sought out over the coming days, so please bare
with us as we sought everything out and start whenever you are ready.

-Tim

NOTE: Mentors if you think of anything additional, please feel free to add
to what I've already mentioned.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.blender.org/pipermail/bsod-mentors/attachments/20060620/4aee07d4/attachment.html