chapters (to begin with):
from “Diving In” and “Interface”
[list]
Overview (new)
Installation (new)
Getting Started
Animation Basics
Adding Layers
Creating shapes
Flower Animation
[/*:m][/list:u]
So we do have OPEN (not assigned):
“Overview” e
“Installation” e
“Getting Started” e
“Animation Basics” e
“Adding Layers” e
accepted work items (responsibilities / planned finish date) Thank you!
#8 “Overview” a,b,c,d (Oho, 15.5.2010) #9 “Installation” a,b,c,d (Oho, 15.05.2010) #10 “Creating Shapes” c (ghosthand & Zelgadis) #11 “Creating Shapes” e (pixelgeek) #12 “Adding Layers” c (ghosthand) #15 “Flower Animation” c (Zelgadis)
finished work items Thanks a lot!
#1: create Documentation section in Forum (genete / 14.04.2010) #2: establish Documentation mail list (genete / 14.04.2010) #3: inform users / community about planned restructuring (oho / 15.04.2010) #4: repair/remove misleading links on wiki left navigation bar (zelgadis / 15.04.2010) #6: add screen shots chapter to writers manual & link to discussion (oho / 15.04.2010) #5: add screen shots rules to writers manual as soon as settled (oho / 20.04.2010) #7: define list of work items for first set of chapters (oho, 23.04.2010) #13 “Getting Started” a,b,c,d (Zelgadis, 06.05.2010) #14 “Animation Basics” a,b,c,d (Zelgadis, 06.05.2010) #12 “Adding Layers” a,b,d (ghosthand, 06.05.2010) #10 “Creating Shapes” a,b,d (ghosthand, 12.05.2010) #15 “Flower Animation” a,b,d (Zelgadis, 12.05.2010)
explain current structure / restructuring plans
I have wrote some notes about structure/writing policies here: synfig.org/wiki/Writer_Documentation
setting targets for docs
I think the first target for docs is pdf document generated from Manual (synfig.org/wiki/Category:Manual) and updated for 0.62.01.
describing content for docs
Notice, that manual not covers every aspect of Synfig. It’s purpose to guide you through essential concepts of animation production process in Synfig Studio. If you need a complete list and detailed description of each Synfig function, you should take a look to Reference.
I’ll write more about current structure / restructuring plans tomorrow. Good night!
That is good as it is! I meant something different:
you have created a structure for the Manual already and we should review that.
Why do you put things into this structure the way they are (DivingIn->Interface->ArtworkImport-> …)?
I believe there are good reasons behind the structure as you’ve done it.
Will that be a good reading experience when we look at the manual as a “book”?
Will it fit into the target thoughts we have defined (see below)?
Sorry, need to be more precise in what I mean:
we should be clear about our target audience and the target level of information to be “teached” per wiki page
There might even be several entry points for different readers
animation beginners
animation users
animation experts
users of former versions of Synfig Studio
…
As stated above, as soon as we have the target (user and content) defined for a wiki page we should then check that page
Why do you put things into this structure the way they are
When I developing structure for the manual I started by looking through all pages on the wiki.
I have realized that we already have good “beginners guide”, written by Darco - that 's a sequence of pages:
Getting Started
Animation Basics
Adding Layers
Creating shapes
Those pages giving a quick start to any beginning synfig user - that was the strong point. I think all people here started to learn synfig from those 4 famous pages. ^___^
All other pages were quite unsorted.
At first I tried to build structure with perfect sequential/logical explanation of all synfig concepts, starting from elemental concepts (axioms) and rising to the complex methods. Like geometry. I wanted to extend those 4 pages in that way. But practice showed that any my attempt to extend those 4 pages lead me to loss of all advantages those tutorial sequence have - simplicity, quickness, intelligibility.
After reading some books (manuals) I realized that all of them which are most interesting to read for me are not perfectly sequential. They usually have short introduction at the beginning without deep explanations to show “how things work” at glance. The deep explanation of concepts goes after that section by section. So the reader gets the idea in first section and gets the general idea. After that he can continue read through manual or jump directly to the section he is interested in. So I gave up on “perfect sequential explanation” and said “Great! We have first section!”
After that I started to looking through all wiki pages again trying to group them by similar subjects into sections. I end up with “Diving In”, “Interface”, “Artwork Import”, and others listed on Manual wiki page.
Then I started to think about the sequence of sections. It was obvious that here we should be sequential. From easy to complex, from basic concepts to techniques.
I started to think. User learning synfig to make animation. But to make animation he needs artwork. How can he get it? Construct by himself or… let’s be honest: synfig is not a drawing program yet. Yes, you can draw from scratch in synfig, but if you want good artwork, then you draw a draft first (say in GIMP), then import and trace over it. Import! That’s it! Basically you might not need to construct artwork at all in synfig if you making, say, cutout animation or drawing everything in Inkscape… When user starting to work with synfig he wants to get to the animation as fast as possible and let’s tell him the easy way first - import. OK, but before that he need to get familiar with interface for sure. So I’ve got:
Interface
Artwork Import
Artwork Construction
Animation
Output
That reflects the very common workflow for animation production process. User opens application, imports something, composing alltogether, animates and renders. Notice that in general “Animation” stage is not mandatory, because person may use synfig to produce static artwork. That’s just a side note.
Then I started to split the huge sections: “Artwork Construction” and “Animation”.
Linking is a significant and complex feature of synfig related with Artwork Construction. But in general case user can live without it. Also there are some artwork construction techniques based on the linking features. Thus we got three sections: “Artwork Construction” itself, with basic concepts of creating, editing and composing vector and bitmap data; “Data Linking” - about linking stuff; “Advanced …” don’t know what, maybe “Advanced Techniques” - talking about complex examples of artwork construction involving data linking.
Chapter sequence for “Artwork Construction” starts from the “Bline tool” as the main tool for making vector images. User should learn how to use it. After that he shoud learn about the outlines and regions - as products of bline tool. After that he should learn how to change colors. Then goes advanced drawing with Draw tool and Width tool. Now it’s time to learn to structurize outlines and regions - here goes paste canvas layer. Children lock is important trick to structurize composition. After user learning paste canvas layer and “Incapsulate” function he can use gradients. At the same time he learns onto blend method. Finally he learns how to mask things. That should be enough to construct image of any complexity. (I think we should remove “Blend Method” chapter, because it’s just boring describing of all blend methods. It’s place in Reference.)
Chapter sequence for “Data Linking” starts from simple linking, then extends to linking params with various names through export, then describes complex links with converts. After that user can understand sewing blines. We also must talk about our shiny “Link to bline feature”. Next it’s time to explain that all that possible thanks to valuenodes. And finally user learns how to link data between files.
“Advanced Techniques” have no special order. Maybe “Slideshows” chapter should go last here to set the stage for “Animation” section. It’s obvious that Duplicate layer and Brushes features are about artwork construction, but we can’t explain them without introducing data linking. That’s why they are here in separate section.
I have split “Animation” into “Animation” (describing basic concepts and elements) and “Animation Techniques” (describing high-level techniques).
Chapter sequence in “Animation” sequence is quite obvious. A few words about “Animation Techniques”. In my concept this section should describe 3 animation techniques possible in synfig:
Morphing
Cut-Out
Frame-By-Frame
But “Frame-By-Frame” is not written yet. The idea is that if user masters all that 3 types of animation in synfig, then he can produce animation of ANY complexity by mixing those techniques. To be honest, I planned 4th chapter called “Character Animation” explaining how to make complex animation by mixing all 3 techniques, but it’s still have to be done.
“Output” section is clear enough. I think we should merge “Render options” and “Render Dialog”.
Last one - “Configuring Synfig” is similar to appendix - is about stuff someone may need during synfig usage, not directly related to the process of animation production. All the rest goes to Appendix.
Will that be a good reading experience when we look at the manual as a “book”?
I think it will. Of course we should rework/merge some pages, but I hope I clarified general idea.
Will it fit into the target thoughts we have defined (see below)?
I think yes.
I think the entry point for animation beginners/users/experts will be the same.
I will specify target level per page/section tomorrow if it’s still be needed. ^___^
Zelgadis,
thanks a lot for this explanation, that is realy great.
Not only because you explained it to me in an easy to understand and consistent way, but also because your words here are in many cases the missing link between the chapters and/or the missing intro into the documentation for a first time (and maybe even for a quite experienced) reader.
So, I guess, we will use much of this in the final doc as general intro, chapter intro and/or between chapters /pages. I really like what I see here! congrats!
I think I need a few days to understand all aspects, do some reading in the wiki in the light of your explanations.
I also started to analyze docs from other 2D animation SW vendors (yes, commercial) to see what they do well or not so well, so that we might learn a bit from there. I read those a while ago, found them quite easy to start with. Their writing syle is mainly:
quick intro -> tutorial -> learning stuff -> tutorial -> learning stuff …
So, maybe we should think about bringing in more tutorials. BTW in “the 4 famous pages” we find a comparable structure already.
Yes, I noticed that too. Proposed structure fits that scheme quite well.
“The 4 famous pages” are “quick intro”, then we have “learning stuff” → “tutorials” → … cycle.
I.e.:
In “Artwork Construction” we have learaning stuff, but at the end there is a tutorial (Masking)
“Data Linking” is generally learning stuff, and following “Advanced Techniques” are tutorials.
Guys, it is great read you both talking and updating the wiki. I wish to have more time to contribute but I need to settle down a bit more.
Only focusing on new release now.
*Interface
*Creating An Object
Example: Region Color, Outline Color, Layers Concept
Tutorial - Create a circle with Region Color and Outline Color
*Animation Basics
Example: Keyframe, Time, Tweening
Tutorial - Move Circle across screen & preview animation
The new user wants to create an animation as quickly as possible. So we should let them do this by giving the bare minimum info to do this. The first thing any newbie will do is try to create an object first, not import an object. If you really want to talk about import here, then I think we should provide a sample file to import. The biggest complaint I hear from potential users is that they tried but couldn’t get anything done.
After reading the getting started guide, the new user should say “Well, that was easy. I wonder what else I can do or I wonder what this parameter dialog does.” Then I think they’ll explore the manual more: Object manipulation, Layers effects, Advanced Animation, Output.
@ghosthand:
interesting, the latest discussions Zelgadis and I had were about getting Newbies up to speed.
I had (and still have) the same problems getting into Synfig that you descibed.
As I am quite new (at least to Synfig) I will try to write some intro pages
and will mainly work on the first set of chapters,
hoping I could preserve my “Newbie”-feeling as long as possible…
Any help is welcome…
As for the “Import” I think that at least a simple import (">"-“File”-“Import”)
should be mentioned before we explain the rather complex import scripts.
I would even move the “complex import” chapters to a “howto” or “experts” section later on.
We should have an example of a picture (.png/.jpg) and a SVG import.
And, yes, we should provide sample files for that.
(Let’s discuss packaging / delivering sample files in a separate thread)
Update:
I just checked the results of the poll on the synfig.org website.
In the poll we have:
Do you think we can have the diving in section done before the next release. It would be ideal (time permitting, of course).
@zelgadis
At this point, do you want help with the “Diving In” section? I don’t want to delete or change anything that could screw up your writing process.
I don’t like the idea of delay the release to wait for documentation. Documentation is a continuous improvement and should not loose strength after the release (what might happen if the release is a milestone). Also I think that it is better to update the documentation with a running version in the street.
-G
@ Genete:
sorry, but I disagree…
Documentation is always part of a product, at least as important as the rest.
We should make some marketing noise when we have release of the new version.
New people will then be interested in Synfig…
Therefore we should at least have the docs in place to give “Newbies” a fair chance
for a good first impression with Synfig. The Diving In Chapters are the ones we need for this.
Back to the current situation at Synfig:
yes, there is a lot to do. We need to fix all outdated doc material,
but I agree that we should try to get the intro chapters ready asap…
… and if ever possible before release of the new version.
@Genete
I wasn’t saying that we should delay the .62.01 release. But we could maybe speed up writing the “Diving In” docs and finish by your release date. Therefore, the doc writers would have a goal to try to reach. I would have some extra time now to work on reaching this goal.
Oho is correct. It would be great to not only announce the .62.01 release but to also announce the availability of the “Diving In” docs/tutes at the same time.
@oho and ghosthand,
ok I understand. Let me release the candidates and then join you for update the more critical docs needed.
I don’t mind to delay the release a bit but I understand that it should be handy to have all the features running to take the proper screen shots and to mention the last improvements in the basic documentation, specially the keys conbination of the transform tool can cofuse some newbies.
-G
I think I will be able to finish it before release time if nothing will go wrong. It’s a good idea to release first manual section. During our work on manual we can release few snapshots including more and more sections.
Yes, you can!
The big help is to read through the content of “Diving In” section and carefully check if it is correct for current development snapshot of synfig studio. For example you need to replace “Background/Foreground color” to “Outline/Fill color”, sometimes “panels” are called “dialogs”, which is wrong, etc. Just look through a text following its recommendations and fixit accordingly OR at least (if update requires significant structure changes) put notes about found “bugs” on the talk pages, like Oho did. Every note is a big help.
This can be added to Zelgaids’ list as #3:
we need native speakers to proofread the german, russian, spanish English we produced. Seems like you’re from the US…
I would like to define work item packages…
let’s discuss that here now…
What about:
work items for each chapter:
update chapter structure / readability
content: correctness
content: screen shots
content: up-to-date for 0.62.01
proofread (native speaker)
chapters (to begin with):
from “Diving In” and “Interface”
Overview (new)
Installation (new)
Getting Started
Animation Basics
Adding Layers
Creating shapes
Quick Overview
Interface
Idea is, that we will have a writer for each of 1a, 1b, 1c, … 2a, 2b, …
Everybody can still contribute by reading the other chapters and adding ideas/thoughts to the discussion pages.
By this it should be clear where we still need help and double editing (and frustrations) can be avoided.
