About Documentation (Split topic from: New forum version and theme)

Started by Jo Kariboo, August 06, 2019, 09:06:12 am

Previous topic - Next topic

WAS

Quote from: Dune on August 09, 2019, 02:49:19 amI don't see many users here who crave for video's, the 'community' consists of only a handful people. If anyone is interested in making a video about the shipped tgd's (I don't even know what ships with it actually), feel free. I won't do it, I'd rather stick to answering specific questions, and once in a while make a tgd with (extensive) notes of some subject. Like the latest (free) beach. But even that feels like wasted time, as I never see anyone responding, or showing its use.

But I think this goes beyond the subject of this thread.  :-X 

I would do videos but I have too much background noise. I have sat down 3 times and each time was interrupted. My kid crying cause it's silent, yanking headset off, random rangers coming by to drop off food my fiancee sent home. Lol I do better just answering and showing example for now. Plus I really hate to do the editing part. Lol I don't have after effects, which I know, so HitFilm is just trial and error for me. Haven't sat down to learn it.
Check out my Terragen Discord: https://discord.gg/Vy5FRTE

DannyG

Quote from: Dune on August 09, 2019, 02:49:19 amI don't see many users here who crave for video's, the 'community' consists of only a handful people. If anyone is interested in making a video about the shipped tgd's (I don't even know what ships with it actually), feel free. I won't do it, I'd rather stick to answering specific questions, and once in a while make a tgd with (extensive) notes of some subject. Like the latest (free) beach. But even that feels like wasted time, as I never see anyone responding, or showing its use.

But I think this goes beyond the subject of this thread.  :-X 

Understand your point of view Ulco, I have seen & heard from many users asking for videos on social media outlets as well as in my NWDA inbox. That's why I proposed the video tutorial approach. Also PS has done a few videos in the past, so that's at least something they are willing or are able to do for the community. Lets face it we are not going to get any documentation. It's not going to happen. Ulco what you do for the Community is priceless, your technical knowledge and continuous support has helped many over the years. I am sure I speak for many users by saying thank you for your time on that.   



Quote from: Matt on August 09, 2019, 04:35:26 amThanks for changing the subject, guys.  ::) Now we might have to split this topic, which is a messy business when some replies refer to a mixture of both subjects. :'(

There's nothing wrong with asking about documentation but it would be better in its own separate topic.

Considering the subject matter I am completely surprised at selfish nature of this reply. Some of us spend a ton of our time supporting & prompting this software and you're going to drop in not to address the issue but to complain about about a split thread? We deeply apologize for the burden ::)

Jo Kariboo

Quote from: DannyG on August 09, 2019, 10:30:12 am
Quote from: Dune on August 09, 2019, 02:49:19 amI don't see many users here who crave for video's, the 'community' consists of only a handful people. If anyone is interested in making a video about the shipped tgd's (I don't even know what ships with it actually), feel free. I won't do it, I'd rather stick to answering specific questions, and once in a while make a tgd with (extensive) notes of some subject. Like the latest (free) beach. But even that feels like wasted time, as I never see anyone responding, or showing its use.

But I think this goes beyond the subject of this thread.  :-X 

Understand your point of view Ulco, I have seen & heard from many users asking for videos on social media outlets as well as in my NWDA inbox. That's why I proposed the video tutorial approach. Also PS has done a few videos in the past, so that's at least something they are willing or are able to do for the community. Lets face it we are not going to get any documentation. It's not going to happen. Ulco what you do for the Community is priceless, your technical knowledge and continuous support has helped many over the years. I am sure I speak for many users by saying thank you for your time on that. 



Quote from: Matt on August 09, 2019, 04:35:26 amThanks for changing the subject, guys.  ::) Now we might have to split this topic, which is a messy business when some replies refer to a mixture of both subjects. :'(

There's nothing wrong with asking about documentation but it would be better in its own separate topic.

Considering the subject matter I am completely surprised at selfish nature of this reply. Some of us spend a ton of our time supporting & prompting this software and you're going to drop in not to address the issue but to complain about about a split thread? We deeply apologize for the burden ::)
I totally agree!

DannyG

Something seems to me missing above. Perhaps a glitch in the new forum software it's now removing posts? :o

Matt

Hey guys,

I felt that splitting the topic was necessary before I replied. I guess I was asking for trouble by complaining about that before replying to the subject itself. Sorry about that.

At the moment our documentation is the Planetside Software Wiki: https://planetside.co.uk/wiki/

We are making improvements month by month, year by year. Over the last couple of years we've made hundreds of edits, cleaned up or finished dozens (maybe hundreds?) of old pages, added a substantial amount of new information. We've worked with a professional writer to finish some of these documents, reorganize a lot of the older material and write new user guides. Right now we are working with Terragen user and VFX artist Kevin Kipper (@RedMaw). He is writing new user guides which will be linked into the Wiki very soon. And we continue to edit and add to the existing content on a semi-regular basis. There is a ton of material in there and we do what we can with time and money that we have, while balancing that with providing support, maintenance, bug fixing and developing new features on the software itself.

So far the Wiki has:

User Guides (16). These range from Getting Started to more Advanced topics. More are being written right now.

Node Reference. For Function Nodes I believe this is mostly complete. When you find unfinished entries, please let us know. I know that there are still gaps in many of the entries that are not function nodes, but again, please call out specific pages where you wish the information was complete.

References for: Input Settings, Menus, Windows, Animation, Import/Export, Global Illumination, Render Layers/Render ELements, Preferences, Command Line.

There's a lot of material in there, but we know it's not finished. I think it would help us to hear from you which parts of the documentation are most important for us to finish first, so please point us to specific things you want to see first.

So let's get down to figuring out what needs to be done next, and we'll focus on those things.
Just because milk is white doesn't mean that clouds are made of milk.

Matt

Quote from: DannyG on August 09, 2019, 02:18:53 pmSomething seems to me missing above. Perhaps a glitch in the new forum software it's now removing posts? :o

If you mean my post, I thought it was a bit odd to include it when it was talking about doing a split which already took place by creating this thread.
Just because milk is white doesn't mean that clouds are made of milk.

bobbystahr

Quote from: Dune on August 08, 2019, 06:01:07 amStill, even taking one node, you can't write everything down that can be done with it. As said it all depends on connected nodes, and one extra misconnection by some user and the description fails to deliver.
Trial and error, experimentation, and (un)educated guesswork are the keys to understanding the software. I have actually hardly ever read anything in the wiki.



I quite agree, that's what makes TG so much fun...the "easter eggs" you find while messing around.
something borrowed,
something Blue.
Ring out the Old.
Bring in the New
Bobby Stahr, Paracosmologist

WAS

Quote from: bobbystahr on August 09, 2019, 03:37:17 pm
Quote from: Dune on August 08, 2019, 06:01:07 amStill, even taking one node, you can't write everything down that can be done with it. As said it all depends on connected nodes, and one extra misconnection by some user and the description fails to deliver.
Trial and error, experimentation, and (un)educated guesswork are the keys to understanding the software. I have actually hardly ever read anything in the wiki.



I quite agree, that's what makes TG so much fun...the "easter eggs" you find while messing around.

It is fun to mess around, but it's no different than any other software... Especially node based with sound competent documentation. User error is just that. You can not factor that in... Lol Documentation covers each components itself. Not the plethora of uses. It allows you to understand what a node can accept, output, it's setting limits if there are any, and possible quirky behavior you may get exceeding any possibile maximums, etx. It than shows you usage in a simple way... Not going into anymore detail beyond that one basic usage. That's for How To books with specific goals.

A competent reader would than inherently know much more about the shader and all the possible uses they could attempt, which leads to possible user error.

And continuing to make these excuses on behalf of user mistakes because they're not being coddled in a How To Tutorial book which is not documentation, will not help documentation get written... as it makes it exponentially more complex and off-topic from a docu. How To books covering tons of areas of use are written by users familiar with the in and outs of a software through documentation and experience with it [after reading docu and working with the software].

Things are so out of perspective here with users having spent years doing trial and error which is not standard and should not be assumed to be that it's getting way off track from software documentation... 

If we really want to help we need to think like an end-user consumer that works in these fields and what they're used to in documentation outside community space, which covers the softwares basic use, which than allows them to pick up any tutorial and follow along without being confused by the user using macros and complex techniques not covered, or covered in tutorials past. This is NOT proper learning of a software, and why I don't even use tutorials. Learning a software by tutorial alone is where all that user error comes from with no real grasp of the functionality beyond "We're doing this to do this"
Check out my Terragen Discord: https://discord.gg/Vy5FRTE

Matt

I wouldn't state it in such black-and-white terms. I think different people learn in different ways. Some want tutorials, some want pure reference manuals, others want a form of documentation which is something in between. Ultimately we need to provide all of these things.
Just because milk is white doesn't mean that clouds are made of milk.

WAS

Quote from: Matt on August 09, 2019, 04:52:56 pmI wouldn't state it in such black-and-white terms. I think different people learn in different ways. Some want tutorials, some want pure reference manuals, others want a form of documentation which is something in between. Ultimately we need to provide all of these things.

Than you have people which are technical minded (like most the industry of active people, not learners) are blocked out with redundant information just to get to what they need. Documentation should be documentation. Tutorials should be tutorials. Reference manuals should be reference manuals. There's no reason to blur these lines and create chaos and confusion.

Take Blender and other docuemtation. They have their own websites for community driven tutorials, while there manual is black and white, as you put it, in order for the information to be conveyed in a straight forward and interpret-able way.

Look at their Perlin 2D page for example: https://docs.blender.org/manual/en/latest/render/freestyle/parameter_editor/line_style/modifiers/geometry/perlin_noise_2d.html?highlight=perlin

Already, from what people are saying here, this page should be like 5 pages long, encompassing "dozens" of possibilities.

That's simply not appropriate! We should assume people have some technical background to be picking up the software, to begin with, and not assuming you should be educating them there. Same for things like complex function usage. Teaching people Math is not Planetsides job. xD

And yes, Perlin Noise is gone into more detail, in the community space, through tutorials, and forums. Because people take this information and apply it to ever come up with new methods, or even standard methods we use today.
Check out my Terragen Discord: https://discord.gg/Vy5FRTE

Oshyan

I think this example from the Blender docs is interesting and instructive. We actually have this and more in the equivalent wiki docs page:
http://planetside.co.uk/wiki/index.php?title=Power_Fractal_Shader_v3

WAS is right that official docs are not necessarily the place for a ton of very specific individual examples of use. That being said we'd like to work to accommodate something like that if there is indeed demand for it and people ultimately find it helpful. Matt and I are in discussion about that now.

I also want to address a few other specific things:

First and most importantly, money and time are being spent on the docs problem. It turns out to be a more time-intensive and costly thing than you'd hope. But progress is being made. As Matt mentioned, there is new content and updates over the last few years, and the articles from Kevin Kipper are coming online soon and will be a nice infusion of valuable instruction and content. There will also be some resulting videos oriented more toward inter-application workflow down the line.

We have also tried to work with various people and even training companies over the years to create video tutorials in particular, but it hasn't seemed to work out so far. I honestly don't know exactly why this is the case, perhaps there just isn't enough money in it, but I think it's important you all be aware that the lack of output is not for lack of trying! We've been in touch with Gnomon and others in the past and it just hasn't panned out. We still have some active discussions going on and hopefully they'll bear fruit at some point. In the meantime if you'd like to see such content from an established training provider, let them know, request it! It will probably help us move these deals along.

Another point worth mentioning is that recording good video tutorials is actually (from my experience) harder and more time consuming than it seems. Some people who are very experienced at it probably can do it much faster than I or some other people can. But for me it takes hours to produce 10 minutes or so of high quality video, from writing a script (even a basic outline) to testing to recording and re-recording (because there are inevitable mess-ups), to editing. To create a full scene breakdown workflow generally takes a good deal longer.

Blender's community is absolutely amazing. Perhaps it is in part *because* it's free that there is so much contribution and giving back. It's also just a much more broad appeal software, which means lots more potential (and actual) users vs. Terragen. Our own much smaller community contributes wonderfully too, but there are just fewer of us, it's a lot harder to spread the load. I will say though that from what I've seen there's a lot less snark and better attitude toward new members (newbs!), etc. here, so we have that going for us (i.e. a nice[r] community). :D

Finally, the Wiki had to be closed to general edits because of massive amounts of spam. But we are happy to enable edit access to individuals who demonstrate an ability for and interest in contributing. Just email us and we can discuss what's involved.

- Oshyan

DannyG

I am surprised it took a business manager this long to estimate or "figure out" what the cost would be as this should have been #1 on your list of things to do as the community has been decimated because of this. From a business standpoint that is a serious problem. Also leaving everyone in dark over the years with empty promise after empty promise is not fair to the customers, its not like we haven't been inquiring. That said I personally do not have anything positive to contribute to this as I will believe it when I see it. Right now this is just filed under the dozens of other threads exactly like this. Sorry for my bitterness but at this point a bit of bitterness from everyone is justified.

Dune

I'll have another short say in this. I can understand everyone's view, but bitterness and harshness is a bit too much, I'd say. From what I just saw (and occasionally checked) on the wiki pages, it's pretty indepth and comprehensive, and there are quite a few good tutorials. Enough to be able for a novice (after having read and understood the basics from those pages) to get a good landscape out of TG, and take it from there.
Of course some areas may need a bit more indepth explanation, but that's also what a dedicated forum (and I'm not talking about FB of Twitter or whatever) is for; asking, and checking whether some problem or trick has been covered before.
And with limited manpower and financial grounds, what more can be expected than there's available now. 

jwiede

Ugh, editor ate quotes and mangled reply, need to try again from start, sorry.  What's up with the post editor?

jwiede

Quote from: WASasquatch on August 08, 2019, 03:44:11 amI've asked for the wiki issue to be resolved or switch to a better system before so we can make edits (maybe make accs for us users by request), but In reality, as I mentioned above, it won't be true documentation.

However, it would likely provide a strong reference base from which more thorough documentation could be derived, and because of its peer-reviewed nature, might not even require as "deep" attention and review from Matt in the process -- not every issue is a technical monster, after all.