Thoughts...  

Suggestions for our documentation.
Suggestions pour améliorer la documentation.
User avatar
klausesser
Member
 
Topic author
Posts: 8441
Likes: 2 posts
Liked in: 30 posts
Joined: Mon May 22, 2006 12:18 am
Location: Duesseldorf, Germany
Info

Thoughts...

by klausesser » Fri Mar 21, 2014 4:27 pm

Annis wrote:Have you ever read something in our documentation and wondered "what on earth does that mean?"?



Permanently . . =D :cool:

best, Klaus (appreciate the effort definitely!)

User avatar
gkaefer
Member
 
Posts: 3434
Likes: 0 post
Liked in: 2 posts
Joined: Tue Jun 09, 2009 1:01 pm
Location: Salzburg
Info

[IDEA] Re: What is this new sub-forum?

by gkaefer » Fri Mar 21, 2014 11:02 pm

klausesser wrote:
Annis wrote:Have you ever read something in our documentation and wondered "what on earth does that mean?"?



Permanently . . =D :cool:

best, Klaus (appreciate the effort definitely!)


a listing of each single Setting:
+ with screenshot where this Option can be found
+ a Brief explanaition what is this Setting for (like this one: http://www.autopano.net/wiki-en/action/ ... Papywizard )
+ A detailed desriptions (no found until now in docu, sorry) with links to more technical/mathematical/theoretically explanations of this Setting (like this one: http://www.autopano.net/wiki-en/action/ ... _RMS_value) This detailed description should explain why & when to use this Setting, explaining the Impacts if using/changing this Setting etc.
+ A Listing of all possible values of this Setting explaining exactly what the Impact is using this value (example: why and when have I to move the blending Level value from Default -2 to -1, which Change have I to expect if doing so, what can be achied using this, which sideeffect will popup which negative Impact will arise if available...)
+ in sum the docu should gives you a guide how to use the Software to get a perfect Panorama rendered on first try and not a vague map to start your try and error Marathon...
+ a final documentation should be available contenporain with the first non beta Software Version.
+ a documentation should also be available in layouted readable printed book version (and yes I'm willing to pay for this too if it does have the Quality like Bloch's "The HDRI Handbook 2.0" and yes I also bought Version 1 of this book...)
+ a wiki page just somehow converted to pdf format is useless (where is the pdf docu from Alpha tests?)
+ hire a Person locally based at your Office responsible for writing the technical documentation. This Person should be no programmer, it should be a (Hobby?) photographer willing to lern to create panos. If a question does popup he should visit the collegues to ask his questions...

Liebe Grüße
Georg

User avatar
klausesser
Member
 
Topic author
Posts: 8441
Likes: 2 posts
Liked in: 30 posts
Joined: Mon May 22, 2006 12:18 am
Location: Duesseldorf, Germany
Info

Re: [IDEA] Re: What is this new sub-forum?

by klausesser » Sun Mar 23, 2014 2:42 pm

gkaefer wrote:
klausesser wrote:
Annis wrote:Have you ever read something in our documentation and wondered "what on earth does that mean?"?



Permanently . . =D :cool:

best, Klaus (appreciate the effort definitely!)


a listing of each single Setting:
+ with screenshot where this Option can be found
+ a Brief explanaition what is this Setting for (like this one: http://www.autopano.net/wiki-en/action/ ... Papywizard )
+ A detailed desriptions (no found until now in docu, sorry) with links to more technical/mathematical/theoretically explanations of this Setting (like this one: http://www.autopano.net/wiki-en/action/ ... _RMS_value) This detailed description should explain why & when to use this Setting, explaining the Impacts if using/changing this Setting etc.
+ A Listing of all possible values of this Setting explaining exactly what the Impact is using this value (example: why and when have I to move the blending Level value from Default -2 to -1, which Change have I to expect if doing so, what can be achied using this, which sideeffect will popup which negative Impact will arise if available...)
+ in sum the docu should gives you a guide how to use the Software to get a perfect Panorama rendered on first try and not a vague map to start your try and error Marathon...
+ a final documentation should be available contenporain with the first non beta Software Version.
+ a documentation should also be available in layouted readable printed book version (and yes I'm willing to pay for this too if it does have the Quality like Bloch's "The HDRI Handbook 2.0" and yes I also bought Version 1 of this book...)
+ a wiki page just somehow converted to pdf format is useless (where is the pdf docu from Alpha tests?)
+ hire a Person locally based at your Office responsible for writing the technical documentation. This Person should be no programmer, it should be a (Hobby?) photographer willing to lern to create panos. If a question does popup he should visit the collegues to ask his questions...

Liebe Grüße
Georg


I completely agree.

How a Reference Guide should be looking like you can see here: http://akmedia.digidesign.com/support/d ... _73478.pdf

And that´s "just" the Reference Guide . . .

Then there´s the Knowledge Base - about 100MB of PDF:
http://avid.force.com/pkb/articles/en_U ... popup=true

best, Klaus

User avatar
Annis
Kolor Team
 
Posts: 465
Likes: 15 posts
Liked in: 15 posts
Joined: Mon Aug 12, 2013 12:47 pm
Location: France
Info

Re: What is this new sub-forum?

by Annis » Mon Mar 24, 2014 10:48 am

Hello,

Okay, well I'm glad we've already got some suggestions, even if they're posted on the sticky and not actual separate posts. ;-)
For a PDF or a printed form of the documentation, we'd first need to have a more completed and understandable version of the documentation, at least for the book, it's easier to keep a PDF up to date but it would still be best to sort out the documentation first than releasing confusing PDFs... no?

gkaefer wrote:+ hire a Person locally based at your Office responsible for writing the technical documentation. This Person should be no programmer, it should be a (Hobby?) photographer willing to lern to create panos. If a question does popup he should visit the collegues to ask his questions...

That's what we've done for the Panotour Documentation, what do you think of how it was presented (with the short youtube videos for each feature... everywhere)? Some of the "Kolor-English" will obviously need to be revised, though it didn't seem to bad in this new doc.
The videos wouldn't be very helpful if we put the doc into a PDF though, since they can't be integrated. Same for a book!

gkaefer wrote:+ A Listing of all possible values of this Setting explaining exactly what the Impact is using this value (example: why and when have I to move the blending Level value from Default -2 to -1, which Change have I to expect if doing so, what can be achied using this, which sideeffect will popup which negative Impact will arise if available...)

Like in the PTP2 doc, we're planning on adding short videos that would be able to show the different settings. Too many images make the pages take ages to load, and aren't necessarily more understandable than videos where you can see in "real-time" what is happening.

gkaefer wrote:+ in sum the docu should gives you a guide how to use the Software to get a perfect Panorama rendered on first try and not a vague map to start your try and error Marathon...


Perhaps something like in the AVP doc, "first steps"? With a video, and workflow.

The "My first panorama" video will have to be updated, especially the voice-over..

What are your thoughts on our latest actual video tutorials (with voice explanation, not the soundless videos)?

no avatar
mediavets
Member
 
Posts: 15538
Likes: 1 post
Liked in: 60 posts
Joined: Wed Nov 14, 2007 2:12 pm
Location: Isleham, Cambridgeshire, UK.
Info

Re: What is this new sub-forum?

by mediavets » Mon Mar 24, 2014 10:57 am

Annis wrote:What are your thoughts on our latest actual video tutorials (with voice explanation, not the soundless videos)?


Although I like them as a means of 'documenting' software, videos present a problem for those of us with relatively low bandwidth Net connections.

User avatar
Annis
Kolor Team
 
Posts: 465
Likes: 15 posts
Liked in: 15 posts
Joined: Mon Aug 12, 2013 12:47 pm
Location: France
Info

Re: What is this new sub-forum?

by Annis » Mon Mar 24, 2014 11:07 am

mediavets wrote:
Annis wrote:What are your thoughts on our latest actual video tutorials (with voice explanation, not the soundless videos)?


Although I like them as a means of 'documenting' software, videos present a problem for those of us with relatively low bandwidth Net connections.


That's understandable. How about if we posted the script for the videos as well?
Along with a few images but too many would also be a problem for slow connections.

User avatar
klausesser
Member
 
Topic author
Posts: 8441
Likes: 2 posts
Liked in: 30 posts
Joined: Mon May 22, 2006 12:18 am
Location: Duesseldorf, Germany
Info

Re: What is this new sub-forum?

by klausesser » Mon Mar 24, 2014 12:10 pm

Annis wrote:Like in the PTP2 doc, we're planning on adding short videos that would be able to show the different settings. Too many images make the pages take ages to load, and aren't necessarily more understandable than videos where you can see in "real-time" what is happening.


"Short videos" are nice. But they rarely help as long as the items they deal with are not understood in-deep by the viewer. THAT is the issue.
"Short videos" are too short for being able to explain an item in a detailed way.

Nobody gets help from a video which shows HOW to do something - as long as it´s not clear why to do it the way the video shows in a certain case . . .

So "short videos" never can replace a profound and understandable description of what things MEAN and WHY to use them the suggested way instead of a different way.

Again: the problems are the surfacely explanations which are provided by "short videos". Those videos are great for users who are somehow used to an application anyway. But detailed in-deep knowledge about things like "cutting" or "diamond" in the blend-settings are provided NOWHERE. I use APG now for about 7 years - but i have no idea what "cutting" or "diamond" and others mean in detail . . . and when it´s preferable to use it the one or the other way in the one or the other case.

best, Klaus

User avatar
gkaefer
Member
 
Posts: 3434
Likes: 0 post
Liked in: 2 posts
Joined: Tue Jun 09, 2009 1:01 pm
Location: Salzburg
Info

Re: What is this new sub-forum?

by gkaefer » Mon Mar 24, 2014 6:28 pm

there is no single perfect documentation that can fit to all usage cases for all sorts of users with all different Level of knowhow & personal experiences.
so the Multi method using reference docus, faqs, Videos etc is great. no doubt.
Videos I use for getting preview of new Features I never used before...
if you know you did something before but you dont remember how you did it.... the Videos will fail... and vrey likely the printed docu too...
the reference online docu I will consult If I wanna get an overview over all possible Options to make my result maybe better by tweaking the Settings...
and a detailed reference docu explainging why I should do this or that and not that or this can Show you restrictions/Errors in your workflow etc.
faqs can give you detailed step by step descriptions how to solve comon Problems without the Need to work through hundrets of printed pages...
... but I also wanna be able to consult a printed Manual in cases my two Monitors are filled up with apg Windows, including previews which took minutes to open or CP's editing Windows I dont wanna Close, or just dont wann toggle through 20 search Windows and resulting Forum results....

Georg

User avatar
Annis
Kolor Team
 
Posts: 465
Likes: 15 posts
Liked in: 15 posts
Joined: Mon Aug 12, 2013 12:47 pm
Location: France
Info

Re: What is this new sub-forum?

by Annis » Wed Mar 26, 2014 4:49 pm

klausesser wrote:
Annis wrote:Like in the PTP2 doc, we're planning on adding short videos that would be able to show the different settings. Too many images make the pages take ages to load, and aren't necessarily more understandable than videos where you can see in "real-time" what is happening.


"Short videos" are nice. But they rarely help as long as the items they deal with are not understood in-deep by the viewer. THAT is the issue.
"Short videos" are too short for being able to explain an item in a detailed way.

Nobody gets help from a video which shows HOW to do something - as long as it´s not clear why to do it the way the video shows in a certain case . . .

So "short videos" never can replace a profound and understandable description of what things MEAN and WHY to use them the suggested way instead of a different way.

Again: the problems are the surfacely explanations which are provided by "short videos". Those videos are great for users who are somehow used to an application anyway. But detailed in-deep knowledge about things like "cutting" or "diamond" in the blend-settings are provided NOWHERE. I use APG now for about 7 years - but i have no idea what "cutting" or "diamond" and others mean in detail . . . and when it´s preferable to use it the one or the other way in the one or the other case.

best, Klaus



Oh no don't get me wrong, the short videos aren't there to replace the documentation, and they wouldn't be exactly the same for APG as the PTP videos since the two softwares function differently. For PTP it's showing the different actions of each setting for the plugins and such, which can be shown easily.
The videos certainly wouldn't be as numerous either.
They're meant to be there to illustrate was has already been explained. Of course, if no explanation is provided, the viewer might not understand the illustration.

This page on the rendering engine is being updated for the new 3.5 version, I'll add in a note to see if the cutting types and weightings can be explained more in depth.


Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest