[Bsod-mentors] compiling a list of commands

[Matt Ebb]

On 18/06/2006, at 14:18 PM, Ryan Dale wrote:

> 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.

That's a really good point! Here are a few guidelines that I  
personally think would work. What do you guys think?

* One must assume a certain level of knowledge. Unless you're writing  
something intended for complete beginners who haven't used 3D before,  
then you won't need to link things like 'select' or 'vertices' or 'x  
axis'.

* Only link to something the first time it's mentioned, unless if the  
next time, you're talking about a different aspect of it and need to  
remind people to look at the detailed information again. Eg. you  
shouldn't need to link up something simple like "Add a new cube mesh"  
more than once, but perhaps if you're talking about the loop  
subdivide tool in the context of multi-cuts, and then in the context  
of the 'smooth' option, you may want to link it both times.

* Link to things when you mention something about a tool that's  
potentially more complicated than simply clicking the menu or hotkey,  
that would be more like an aside, but that you aren't mentioning in  
your text. For example, instead of saying:

"Do a loop subdivide with three cuts (press a number key on the  
keyboard when you're previewing the loop cut) and then blah blah  
blah..."

You could use:

"Do a loop subdivide with [three cuts] and then blah blah blah..."    
with [three cuts] -> the reference page that describes the multi-cut  
features.

Of course this depends on what you want to teach. If you want to  
teach people about the functionality in the subdivide tools, then  
you're better off mentioning it in your text. But if that's not  
important and you're trying to teach about workflow, or if you can  
reasonably assume that most of your readers will already know that  
information, then it's probably better to link. It's a balance. The  
less asides like that you include in your text, the easier it is to  
follow the workflow, but the more chance you might have of people not  
knowing about the tools you're showing.

I guess it's up to the writer's judgement, but I'd personally err on  
the side of linking, since we should make use of this wonderful  
medium and not duplicate text and effort everywhere, which not only  
brings inconsistency, but makes the text much harder to maintain and  
keep up to date when it's not centralised.

> 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]?

I'd say the first choice should definitely be to use the name that's  
mentioned in the Blender UI (menus/buttons/confirmation dialog). If  
there's nothing there, then use what's already been used in the  
reference manual. Other than that, well.. who knows...

cheers

Matt