Wings 3D Development Forum
Documentation Strategy - Printable Version

+- Wings 3D Development Forum (https://www.wings3d.com/forum)
+-- Forum: Wings 3D (https://www.wings3d.com/forum/forumdisplay.php?fid=1)
+--- Forum: Documentation Project (https://www.wings3d.com/forum/forumdisplay.php?fid=15)
+--- Thread: Documentation Strategy (/showthread.php?tid=43)

Pages: 1 2 3 4

Documentation Strategy - optigon - 11-20-2012

All you really need to know about Wings 3d

If someone wants to learn to use Wings where do they start?

The Official Manual is sadly out of date and the main problem with writing a new one is that Wings 3d is a moving target.

I've thought about the problem for a long time and the best solution in my opinion is to write a General Overview on how to use Wings 3D.
The other options are:
  1. An exhaustive list of features and options going command by command and feature by feature.
  2. A series of modeling tutorials that show a user how to make something.
Also there is the question of medium.
The two most common contenders these days are:
  1. Video
  2. Text plus images
Videos are great and can be easy to learn from but keeping video documentation current is hard work. If a feature or workflow changes, then the video has to be reshot or edited to maintain its authority. For this reason video documentation is better for static projects where procedures are unlikely to change.

Wings is a dynamic project at its periphery and slightly more stable at its core, but still too much of a moving target to officially adopt a reliance on video documentation.
Text documentation, on the other hand, can be edited quite quickly and can have sections inserted or deleted without having to rewrite everything. The main issue with a text document is it initial production. Writing a long technical manual is a difficult task. A successful manual depends on an agile content strategy. I don't think an exhaustive feature by feature list is the way to go. So I suggest an overview approach.

The advantage of an overview approach to a technical manual for Wings, is that it highlights the important aspects and general philosophy of how to use Wings. Instead of trying to describe every single feature of Wings, an overview would focus on the methodology of wings by describing a selection of key features. The goal of the documentation would be to engender the user with all they need to know to figure out the rest on their own.

An over view approach is easier to maintain and much shorter than an a feature by feature manual, though it would compliment and lend context to a feature by feature manual if one were to be constructed synchronously.

Here is an outline of what I've come up with. Just wondering what people think of this approach.

General Overview
  1. Subdivision Modeling
  2. Make a Cube
  3. Using the Camera
    • Rotate
    • Pan
    • Zoom
    • Aiming the Camera
    • Viewing Along an Axis
  4. Viewing Modes
    • Smoothed Preview
    • Wireframe
    • Orthographic
  5. Selection Basics
    • Selection Modes
    • Mouse Selection and Deselection
    • Deselect Using the Spacebar
    • Bounding Box Selection
    • Increase and Decrease Selection
    • Edge Loops and Rings
  6. Basic Commands
    • Move, Rotate, and Scale
    • Extrude
    • Smooth
    • Cut
    • Connect
    • Bridge
  7. Advanced Selections
    • Infoline
    • Secondary Selections
    • Move Along Vector
    • Rotate Around User Defined Centre
    • Magnets
  8. Advanced Commands
    • Flatten
    • Intersect
    • Bend
    • Circularise
  9. Advanced Features
    • Virtual Mirror
    • Tweak
    • Sculpt
    • Magnet Mask
    • AutoUV
  10. 3D Coordinate System Basics
    • Axes
    • Coordinates
    • Points
    • Vectors
    • Planes
    • Normals

In addition, none of these headings would be dsicussed exhaustively. Just enough info to figure it out. So for those familiar with the doc I wrote for Tweak on the website -- that is too much info and at best, could be added as a link towards the end of a much briefer summary.

RE: Documentation Strategy - oort - 11-21-2012

optigon,
I agree with your approach. It is similar to what I tried to do with "The Wings3D Handbook". It would be good to expound on the basic information as well, as you did with Tweak. Starting with the basics is a good way to get the ball rolling.

I would put "3D Coordinate System Basics" after "Subdivision Modeling". (Maybe you put that last because it would be a boring subject)

Then "Make a Cube".
Followed by "Using the Camera"

Then talk about the GUI including the Information Line, Information String, Outliner, Geometry Graph, Context Sensitive Menus, Hotkeys.

Followed by "Viewing Modes" and the rest you listed.

In my Chapter Review section of "The Wings3D Handbook" I had started showing before and after images for the various commands. I only got as far as Intrude and Bridge. I think it is a good way to display what a command does.

Just my two cents if interested... Smile

oort

RE: Documentation Strategy - micheus - 11-21-2012

(11-21-2012, 02:09 AM)oort Wrote: I would put "3D Coordinate System Basics" after "Subdivision Modeling". (Maybe you put that last because it would be a boring subject)
I agree.
This kind of subject is used to show some general information about 3D modeling. (it's as I see them)

But, I think that the general Wings3d GUI information should follow them - at least, be put before "Using the Camera".

RE: Documentation Strategy - oort - 11-21-2012

Micheus,
You are right GUI should go before Camera.

On a side note, at first I thought it was strange to have Make a Cube so soon but then I saw that having a Cube in the scene makes it possible to see the affects of the Camera... Smile

oort

RE: Documentation Strategy - optigon - 11-21-2012

Thank for the comments...

...so who's going to write it? Tongue

RE: Documentation Strategy - Fonte Boa - 11-22-2012

(11-21-2012, 11:00 PM)optigon Wrote: Thank for the comments...

...so who's going to write it? Tongue

Optigon, i intend to record again wings3Dchannel videos (i can now provide them in hd), probably with audio (just talking name of commands, hotkeys being used, etc): your annotations are very useful to think in organize the video series in a didatic way. For the moment, i would just add a topic about "how to define hotkeys" between the initial topics. Wink

RE: Documentation Strategy - greytery - 11-22-2012

Can I make some comments more or less agreeing with what has been said above about the structure rather than content, please?

The documentation is never going to satisfy everybody. Think of a 3d matrix which depends on the intended audience (X = Newbie, Intermediate, Expert, Developer), what they want to use Wings for (Y = doodling, virtual sculpting, games character building, math modeling..) and their learning styles (Z = visual, auditory, kinaesthetic**). Other dimensions no doubt exist. Filling that void completely is going to more complicated than developing the Wings software in the first place.

I think that the Getting Started, basic(!) concept notes, menu descriptions, simple primitives manipulation are key for those such as myself (- remember, you were a newbie once). So a document Table of Contents structure that relates to the interface would seem to be useful here. (- See the thread on Wings3d Help Dictionary which aims at covering the basics - I think). I hope we can assume most newbies are intelligent users, although that's difficult to define ***. So it doesn't have to be too wordy - just 'complete'. There are a number of good introductory tutorials out there, both text and video - just needs some organised & maintained links to them, in context.

Moving up the axis, intermediate users - and those that have 'got it' - already have the ideas, but need exposure to more advanced techniques. Here is the home for advanced concepts, really smart tricks, showcase modelling examples, i.e. the difficult, but sexy rewarding stuff. In my dreams ....
This is the area for such as the Tweak notes (which I find well written)

That said, optigon's starter list above is 'flat' with basics and advanced info at the same 'level'. So I'd go for a high level split of documentation into Basics and Advanced, with their own sub-pages, Table of Contents, etc.
In practice, the two documentation streams may overlap, hopefully without too much repetition or contradiction, but I think the style would be different. And probably written by different parts of the Community*.


Notes:
*"...so who's going to write it? Tongue "

**kinaesthetic = learn by poking something.

***"your wise men don't know how it feels to be thick as a brick" Jethro Tull

RE: Documentation Strategy - oort - 11-22-2012

I like greytery's idea of breaking things down into a Wings3D Beginners (Basics) page and a Wings3D Advanced page.

Would a new Wiki be started for this??? I can cut and past some stuff from my Wings3D Handbook if it is considered to be good enough. I will have to convert the PDF to text since the original Open Office Doc was lost when my external hard drive died a while ago... Sad How will you control the quality of the information added?

P.S. Can someone recommend free software to convert from PDF to TXT? I haven't looked yet but thought I would ask before I start looking.

Edit: Looks like I will have to use the OpenOffice "PDF Import Extension"... PDF Import.

oort

RE: Documentation Strategy - greytery - 11-23-2012

By wiki, do you you mean Wikibooks?
I don't think there's another 'active' one, and I don't think there's a Wiki facility on the Wings3D website (wherever it is hosted). Is that true?
Anyway, the use of Wordpress and wikimedia software imply two different editorial/control approaches.

Wikis are designed for sandboxy activities, eventually knocking stuff into shape, by a process of evolution, survival of the wittiest - or thickest skinned Smile.

There's still valuable material on the Wikibooks site, even in the archeological sense. I've been looking at the current material with a view to bringing it up to date - but aiming it 'Getting Started' level, because that's where I'm at.
The pdf 'Handbook' also has good 'getting started' stuff in it, but it's not always a straight shoe in to move the material across.
Worth a bash though, isn't it!!?!

oort - if you want to discuss further then drop me a mail.
Cutting text from a (your) pdf file into a wiki is a doddle. (I use Foxit).

NB: Not sure that using Wikibooks purely as a sandbox for material to be moved elsewhere is approved of by the Wiki editors - who can get a bit sniffy about style, bad references, etc. So it should look like we mean it. Cool

RE: Documentation Strategy - oort - 11-24-2012

Yes, I was thinking Wikibooks so that several people could work on it. I don't know much about Wikibooks. I was thinking a new page and leaving the existing one as it is. Are there better options?

Thanks for the offer to help. I will start a new thread in Off Topic to discuss PDF's.

oort