Manual Template Discussion about animation_nodes_manual

[JacquesLucke]

Yes that sounds exaxtly how I imagined it.
Maybe we can also mention complementary nodes like "vector to Euler" and "euler to vector".

And you are right, these extra categories you mentioned are not really needed for all nodes.

Do you think it is easier to write the manual for each node individually or to take some more nodes together and fill out the pages step by step?. E.g. first step is to prepare the files and maybe a small description; second step is to add information about the sockets, etc..

[JacquesLucke]

Also I'm not sure if we should have empty sections in the manual, like the advanced settings for the clamp node.

Sometimes it may be useful to mention corner cases, eg what happens when the max value is smaller than the min value.

[LeonCheung]

True. The format shouldn't be too dogmatic. It needs flexibility in different cases. And I have thought about batch generating a very basic template with the categories above, for each node. But you are right, maybe it may confuse users with a mirage page. So now I think it would be better to copy from any other page then re-edit.

[JacquesLucke]

I think batch generating the files can be difficult in some cases because of dynamically added and removed sockets. I guess you will have to double check every node anyway so maybe it is not worth the time to make this automatic solution, but it is your decision :)

[og76]

fwiw, here's my 2 cents:

1. Node per page or category per page
I was wondering if it's not better to have a page per category rather than a page per node
Like Numbers, text etc In which case the nodes will be sections in the bigger page with link to it but also not navigating in pages subpages so much

this is because

• It's easier to navigate than subsub sub pages
• the whole category needs some explanations
• some nodes are very small (float input, clamp even etc) while some are complex enough that do not make sense but in the context
• some cases are very special (lists, subprograms, debugs) and such template does not help much

Most of all, the issue is that the examples of use are prone to show many nodes at once and some examples are not specific to one node but rather to one use case.

If you like, I will attempt to do an example out of text area to better show what I mean

2. Description of nodes vs nodes in action
I was also thinking that I don't like to see nodes out of context.
Maybe for small ones it's ok, but generally I think the nodes images should be only in context, always showing at least a debug output. It kinda makes them alive.
I know that examples should do this, but it's more of a visual explanation of what text is describing.

I'm not sure if it makes sense, so again, I should probably make an example (yes, text area)
the templates are ok then, well, considering that they could fall into the same page?

3. Or not quite so
Or maybe these could be per node pages out of a bigger page that is more visual...
That means you go into a category with more general explanation and more per usage oriented and you have per node pages only if you need to.
This being a more inviting way that should also promote an understanding of the workflow in AN

OK, I should make an example ..

ps: I like the idea of automation, very procedural ;) well, I hope the above does not spoil it for you

[LeonCheung]

Nice. That's why I opened this discussion. :)

For 1: Imho, we already have a very convenient left-hand sidebar to jump across any level in a flash, so I still think it's not so necessary to put all nodes under the same catetory in a single page, also because:

a.) Some categories can be fairly big, like mesh, spline, text, etc. True that lots of things can be explained in just a few words, but the whole page may grow larger and larger as development going.

b.) Manual is manual, like a dictionary, like a reference book, which should be clearly organized and classified in a sustainable degree.

For 2: Actually we can have both while not making things so messy.

For 3: It seems most categories are already self-explanatory and need no extra explanation I suppose. Once users learn one or two sub items, they will hopefully get the point easily. For more information about details of everything else, I think users will have (and be highly recommended) to turn to learn things from plenty of real cases and tutorials from community, besides the Example section on each page.

And sure I would like to see your examples. :)

[JacquesLucke]

I agree with Leon here. In a manual the most compact form may not be the best. One page per node should exist, even if there is not much on the pages, because when a user does not know what a node does, he should be able to navigate directly to the node with this path: "nodes -> category -> node name".

We have to decide about the primary purpose of the manual.

1. the manual can be a reference where users can find information about specific things or
2. a guide with which the user can learn the addon (project based)

As Leon already mentioned we can have both, it is just more work!
Both purposes should be separated in the manual (with cross-links of course).

No matter what we decide, it will be better than the current manual :D

[og76]

ok, thank you.
I see the point here, maybe I'm talking about a more of a tutorial like thing. And it's not that clear.
Ok, as a basis, a "dictionary" should be there.
As about user guide or more use case oriented variant, well guess we can have both.

For point 3, Leon:
Not quite so. Remember that you are a "power user" of AN, so may seam that things are self explanatory.
But :

• all the list / item area needs an introduction (next to subprograms, that I don't have to tell about here) for the very concept of it. I know it took me a while .. Ok, I ended up digging into py, but that can very easily fall under psychotic behavior :P
• it is not obvious the way AN deals with some blender data: obj mesh is to be modified on a copy, that is a very basic thing people have to be told about etc.
• all nodes do way more than it seams. For example texts can hold text for 2d/3d, or can hold reference to a name or so, strings / prop names, or can even help managing weird lists or format expressions. So I see at least 3 uses for text/string even without weird coding etc:, text, string, format data imported..
• numbers are used everywhere, but can one figure that integer range is so much into polygon indices?

... and so on

Maybe it has to do with blender internals, that one should understand a bit to make sense of AN. Even there, for example SV manual has a introduction to vector, matrix, float etc. Very necessary, but kinda dry on my taste (if I'm thirsty, gimme water not chemical formula..). It describes, but it does not propose the most common relations (matrix transforms a vector..) and relations are ... all about nodal ;).
Is it more important for one to get what a vector is or how it can be used? Sure both, disregarding the order.

All I know is that we usually fail to serve some very basic premises (make sure the device is plugged in and turned on ..)
And then that I like starting from the big picture, as that makes people answer 1/2 of their questions already.

[LeonCheung]

I think we are talking about the same thing, just from different point. :)
I definately agree that some must-know knowledges like what loop is, what matrix does, etc., deserve enough explanation. We can either talk more on related pages, or summarize in one place, with cross links of course. I also care about beginner's feelings, that's why I prefer the dictionary functionality for this manual, but it's okay to have both for sure.(a separate Project Study category might be nice, since it has to have multiple node types involved, and can't be classified to a single one. But we can link it from each type, for further study.)

About cases like the "text" , it reminds me to feel that it can also be helpful to add tip messages when mouse over the Shift A menu.

[LeonCheung]

Oh one more thing, more like a usability idea: when all nodes pages are settled, is it cool to quickly visit page for each node by selecting it then hit some shortcut? I mean, something like you can go to online manual by hitting Alt F1 on everything in Blender.

[hapit]

Hi there,

I want to help. I'm trying AN since last BCon.

My feelings as a beginner:

• First one needs to catch the concept behind AN. The Introduction of the Manual should give an overview and motivate to go further.
• Now i experiment with AN and at some Points I have a Node and I don't know where to put the output in or get the Input from. That's what I wanted to find when opened the manual. Sadly it's not there yet.

My opinions to the above discussion:

• I like one page per node. If its done we can talk about extending the category page to give an easy overview.
• I think the Manual should have following chapters
  • Introduction (Motivation, Overview) including the existing chapters "How to install" and "Getting started".
  • Nodes (the reference manual to each node)
  • Examples/Tutorials (here the nodes are used in context, links to YouTube, etc.)
  • Glossary (here more common terms are explained like matrixes, math functions, etc.,)
• The node page should contain the explanation, input, output, settings, the smallest example possible to get the idea (screenshot) and Links to Examples and Glossary.

I think Jaques or Leon should make the first node as a starting point. Then we can discuss the proposal and if it's final we can write the other nodes in this style.
The best node page if found so far (but can be improved very much):
http://animation-nodes-manual.readthedocs.org/en/latest/user_guide/nodes/number/clamp.html

Let's give it a "fresh" start in 2016.

[LeonCheung]

Hi, yes, the Clamp page is a kick-start page for discussing the formatting things. Probably the real world life tied everyone up? :) But you are right that it's time to start doing the work now. (Actually I've uploaded screenshot images for most nodes for easy reference by further editors.)

Hmm, now you made me feeling that there might be more people that are willing to learn it than we expected, just don't know how to learn and enjoy it BEFORE getting confused or loosing interest. Maybe we should start doing it anyway, although I think there are still a few things needs discussing before that.

As for Jacques, I think it would be better for him to really focus on development, not here (unless he has to or has plenty of time to). But hey, it's an open community. :) Of course everyone is welcome to contribute anytime, even as a beginner.

For me, I'll see what I can do in the following days. As you said, let's give it a fresh start right now. :)

[hapit]

Thanks for starting it again...

I'm wondering if the type is missing in the input and output description.
For "clamp" it's obvious that it is a number, but is it always so easy?

[LeonCheung]

Yes. it should be written to doc, since it is a doc. :)

[JacquesLucke]

@hapit nice to see you here! and thanks for your feedback.

We could also make a "Sockets" section and give a short description of the socket types. And then link to these pages from the node docs...

Personally I think we are talking too much and doing too less here haha (me too xD)
I mean we all agree on the fact that we need pages for individual nodes. It isn't super important that all these pages look the same. It helps for sure, but it's more important to have some more information there at all!

Maybe we should start something like this: Everyone here writes the description for one/two nodes each day (shouldn't take very long I guess). After a few weeks we should have documented most nodes this way.

[LeonCheung]

Oh a quick note: and Alias too, which is used in Ctrl A searcher. I bet beginners will be easily confused by failing to find nodes by searching for in-menu names.

[JacquesLucke]

Oh yes that's right, but I would say only where it makes sense.. Not all nodes have more than one name.

[og76]

If we start talking names, I still have a special feeling about a user searching sockets instead of having them as a complete list. With an emphasis on the confusing (imho) string and text.

[OmarEmaraDev]

I think this was settled. So closing for now.