Break up the User Manual!

  • Author
  • Message
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Break up the User Manual!

PostThu Aug 29, 2019 1:06 am

Resolve has probably the best user manual of any software package I've used in my entire life. But with the addition of dedicated Fairlight, Fusion and Editing pages, having a monolithic PDF manual for everything has made the searchability of the manual all but useless, because of overlaps in terminology between the Color, Fusion and Edit pages.

For example, I have just started using the Fusion page, and wanted to do a simple search for how to zoom in and out of the main viewer. Typing "zoom" into the search field yielded 183 results, and it was difficult to weed out which of the hits were from the actual Fusion part of the manual, and not the Color or Edit portions of the manual.

That's obviously a simple example. Because of this I've gotten into the habit of foregoing the actual user manual, and just doing a Google search for the thing I'm looking for, and hope that some kind soul on a message board somewhere has answered the question already.

Splitting up each module into a separate manual would make things a lot easier to manage, and may even reduce the intimidation factor among some newbies who see a 2937 page user manual, and recoil in fear.
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostThu Aug 29, 2019 2:32 pm

I would vote no on this if BMD were to ask.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostThu Aug 29, 2019 4:10 pm

Jim Simon wrote:I would vote no on this if BMD were to ask.


Please explain.


Sent from my iPhone using Tapatalk Pro
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostThu Aug 29, 2019 5:52 pm

OK.

I think the current manual is fine, all in one.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostThu Aug 29, 2019 6:15 pm

Jim Simon wrote:OK.

I think the current manual is fine, all in one.


I’m not trying to be argumentative, but it would be nice if you can make an actual detailed case for keeping it “all-in-one”, rather than just tersely responding with an “I think it’s fine the way it is” type of reply. I’m genuinely willing to be wrong about this, but just stating a contrary opinion without any supporting detail is not particularly useful to the discussion.

So you’ve never had to search for a term like “matte” or “tracking” for a specific module in Resolve, and have never found it difficult to differentiate between search results from the Fusion section of the manual vs the Color section of the manual?

The state of native PDF searching, at least on macOS, is very poor, so there needs to be a better way to make it easier to search through the manual for topics, given the depth of the application at this point.

In lieu of splitting up the manual, BMD should seriously consider making these manuals “online” manuals, much like how Apple used to have its FCP7 user guide as a web accessible, searchable guide. Then you could at least Google advanced search operators to get more focused search results.



Sent from my iPhone using Tapatalk Pro
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostThu Aug 29, 2019 9:20 pm

Mel Matsuoka wrote:it would be nice if you can make an actual detailed case for keeping it “all-in-one”,


I don't need to open more than one file to get the information I'm looking for.

I would have thought that was self-evident.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostThu Aug 29, 2019 9:22 pm

Mel Matsuoka wrote:never found it difficult to differentiate between search results from the Fusion section of the manual vs the Color section of the manual?


No. The Chapter Name is listed on the page bottom.

Additionally, one can always start the search from the beginning of the relevant chapter, thus skipping all results that come before that chapter.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostThu Aug 29, 2019 9:31 pm

Jim Simon wrote:
Mel Matsuoka wrote:never found it difficult to differentiate between search results from the Fusion section of the manual vs the Color section of the manual?


No. The Chapter Name is listed on the page bottom.


Please explain to me how a user would quickly find search results for information on using "Mattes" in the Color Page, without having to manually sift through dozens of other search results where the "Mattes" in question are referring specifically to Fusion?

Are you seriously suggesting that scrolling down to the "page bottom" of each search result in order to grok the Chapter name is a good, efficient way of finding the information you need quickly?

Again, you seem to be hung up on the fact that there are existing "ways" to accomplish things that people are asking for. What you apparently don't seem to grasp is that there are always better ways of doing things that can make people's user experience much better. My suggestion falls into this category.

As someone who NEVER has to deal with audio, I do not want to sift through search results for topics in the Fairlight page. It adds more friction to the process of finding the information I need to know.
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline
User avatar

waltervolpatto

  • Posts: 10502
  • Joined: Thu Feb 07, 2013 5:07 pm
  • Location: 1146 North Las Palmas Ave. Hollywood, California 90038 USA

Re: Break up the User Manual!

PostFri Aug 30, 2019 4:54 pm

I see both points valid, I too sometimes wish of separate blocks for the manual.
W10-19043.1645- Supermicro MB C9X299-PGF - RAM 128GB CPU i9-10980XE 16c 4.3GHz (Oc) Water cooled
Decklink Studio 4K (12.3)
Resolve 18.5.1 / fusion studio 18
GPU 3090ti drivers 512.59 studio
Offline

John Paines

  • Posts: 5787
  • Joined: Tue Jul 28, 2015 4:04 pm

Re: Break up the User Manual!

PostFri Aug 30, 2019 4:56 pm

A comprehensive index would also be extremely helpful. So, for example, under "Navigate" you'd find "by timecode" as one of the options, as opposed to searching the manual for the right terms which will get you where you want, which is likely to prove time-consuming.
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostFri Aug 30, 2019 6:42 pm

John Paines wrote:A comprehensive index would also be extremely helpful. So, for example, under "Navigate" you'd find "by timecode" as one of the options, as opposed to searching the manual for the right terms which will get you where you want, which is likely to prove time-consuming.


This would be great. But I would feel a huge amount of sympathy to the person who would be in charge of actually building such an index. That would be an insanely huge job!
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline

Hendrik Proosa

  • Posts: 3015
  • Joined: Wed Aug 22, 2012 6:53 am
  • Location: Estonia

Re: Break up the User Manual!

PostSat Aug 31, 2019 8:34 am

Indexes are built automatically if documentation is formatted with any kind of logic.

Personally I'd like a manual that has more actual technical information. As a user guide it works but when you want to actually find information about some technical specific, it is either hard to find, incomplete or casually just missing. A simple example: what kind of color transforms are done between Fu page MediaOut and Edit page in ACES project?
I do stuff.
Offline

Michael Tiemann

  • Posts: 683
  • Joined: Fri Jul 05, 2013 11:22 am

Re: Break up the User Manual!

PostMon Sep 02, 2019 3:45 pm

waltervolpatto wrote:I see both points valid, I too sometimes wish of separate blocks for the manual.


Me too. But I have learned that quotation marks in the search function of OSX Preview App can help me find stuff that is absolutely hopeless without phrase-level search. Still...when the same words are used with very different meanings within different parts of the application (such as mixer--key, layer or audio? or node--color or fusion? fade--video or audio? etc.), it would be great to be able to search only within a relevant part of the manual, not across the whole thing.
MacOS Catalina Version 10.15.7
iMac Pro (2017)
3 GHz Intel Xeon W
64GB 2666 MHz DDR4
Radeon Pro Vega 64 16 GB
RED Rocket-X
Decklink 8K Pro card feeding FSI XM310K Monitor
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostTue Sep 03, 2019 9:50 pm

The monolithic manual approach is definitely made more problematic because of the confusingly overlapping terminology, even within the same module.

Case in point: "Remote Grades" vs "Remote Grading"

These are two entirely different, and unrelated functions within the Color page. Longtime Resolve users already know what Remote Grades are, but this terminology is downright anachronistic and confusing to new users, and I would submit that the function is very ripe for a rename to something more sensible, such as "Linked Grades" or something.

The "Remote Grading" function, on the other hand, is much more self-explanatory as a feature.
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline
User avatar

Marc Wielage

  • Posts: 10901
  • Joined: Fri Oct 18, 2013 2:46 am
  • Location: Hollywood, USA

Re: Break up the User Manual!

PostWed Sep 04, 2019 11:58 am

I asked for this back at NAB, and I don't think it fits with BMD's current philosophy to think of Resolve as a single program.

I would like to see six different smaller manuals:

1) an introductory guide / installation / system requirements

2) overall "quick start" guide of no more than 100 pages for basic functionality in everything

3) a "reference guide" to Resolve Conform & Editing that covers every single menu, mode, and function button

4) a "reference guide" to Resolve Color that covers every single menu, mode, and function button (including Delivery)

5) a "reference guide" to Fusion that covers every single menu, mode, and function button

6) a "reference guide" to Resolve Fairlight that covers every single menu, mode, and function button

I would point out that Baselight provides an "Operator's Guide" (which basically is a course on how to color-correct with that system), a "Reference Guide" (which covers every single function), and an "Install/Config" guide for engineers on how to get the system up and running. I think Autodesk Lustre does the same thing. Old daVinci 2K did this as well.

I do think that 2,962 pages is a bit unwieldly for a single manual. Splitting it up into four or five 600-page manuals is a little more tolerable. I am heartened that the August 2019 manual is subtitled "Reference Manual," so it makes you wonder if there are plans to do other, smaller manuals at some point. Note that there are already separate PDF course manuals on Resolve Color, Resolve Editing, Resolve Fusion, and Resolve Fairlight.
marc wielage, csi • VP/color & workflow • chroma | hollywood
Offline
User avatar

Chad Capeland

  • Posts: 3017
  • Joined: Mon Nov 10, 2014 9:40 pm

Re: Break up the User Manual!

PostWed Sep 04, 2019 3:36 pm

Most of these issues would be solved with context sensitive help.

F1 is the hotkey standard for this, and it's completely broken in Resolve.
Chad Capeland
Indicated, LLC
www.floweffects.com
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostWed Nov 06, 2019 7:07 pm

Just had another thought, in defense of also having on "online" version of the manual.

The problem with PDFs is that while they are indexable and searchable, there's no easy way to link to specific parts of the manual when you want to convey information to someone. You just have to tell someone "search for 'xyz' in the manual", or even just make a screenshot of the PDF, like a bloody caveman.

BorisFX does this for Mocha Pro, and I always refer to that first, instead of the PDF manual.

Having an online version of the manual would help make it easier to point forum posters to specific parts of the manual online, rather than telling them to load up a 3016 page PDF manual and expect them to be able to easily find the information they need quickly (SPOILER: They won't be able to, simply because there's so much keyword noise in the manual due to the different modules in Resolve).

An online version of the manual would also ensure that the reference manual is always updated (theoretically)

Of course, I do think that continuing to have an offline PDF reference manual is also important, but I feel that more people would use the online version by default, simply because it's much less intimidating and easier to use than loading up a gigantic, monolithic PDF manual. About the only time I would ever use the PDF is if I'm on an airplane, or a situation where I don't/can't have internet access, which are legitimate concerns for people who work in corporations or large Hollywood-level studios, but there's no reason why you couldn't have both, assuming the manual is being written in a proper documentation authoring tool.
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline
User avatar

Chad Capeland

  • Posts: 3017
  • Joined: Mon Nov 10, 2014 9:40 pm

Re: Break up the User Manual!

PostWed Nov 06, 2019 8:22 pm

Jim Simon wrote:I would vote no on this if BMD were to ask.


The issue is BMD doesn't even bother keeping the docs current and usable. It's an afterthought and it's problematic because they can't update a single sentence like they could with online docs or even offline HTML docs.

If BMD actually made good manuals (it's not just Resolve, the hardware side has this issue too) it would be tolerable to spend several minutes finding the information you need. But so often the information is missing, outdated, or just wrong.

Marc Wielage wrote:I would like to see six different smaller manuals:


That seems like an easy solution for them. Also could open the appropriate file based on which page you were on when you hit F1. For the most part the manual is broken up like that, and you can hyperlink between files in a PDF.
Chad Capeland
Indicated, LLC
www.floweffects.com
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostWed Nov 06, 2019 8:29 pm

Chad Capeland wrote:
Jim Simon wrote:I would vote no on this if BMD were to ask.


The issue is BMD doesn't even bother keeping the docs current and usable. It's an afterthought and it's problematic because they can't update a single sentence like they could with online docs or even offline HTML docs.

If BMD actually made good manuals (it's not just Resolve, the hardware side has this issue too) it would be tolerable to spend several minutes finding the information you need. But so often the information is missing, outdated, or just wrong.


I take extreme issue with your statement that BMD doesn't make "good manuals".

The DaVinci Resolve manual--for years--has been one of the best software manuals I have ever used, as far as content is concerned. You can tell that a LOT of time and thought is put into writing them, and it's amazing that they are able to spend the time to put out a manual that doesnt read like either an obligatory afterthought written by engineers rather than actual civilians, or unnecessarily overly technical and hard to read documents (e.g. RE:Vision Effects' plugin docs). It's a great example of explaining both what the software features do, as well as explaining, when necessary, why you'd want to use a specific feature.

I'm not sure if Alexis Van Hurkman is still involved in writing the Resolve documentation, but he deserves a lot of credit for adding an incredible amount of value to the original Resolve releases due to his unparalleled skills at technical writing. His Apple Shake, Motion and Final Cut Pro 7 documentation were equally as good.

While the technical presentation of the documentation leaves much to be desired, the quality of its content is unassailable, and it's insulting to imply otherwise.
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline
User avatar

Chad Capeland

  • Posts: 3017
  • Joined: Mon Nov 10, 2014 9:40 pm

Re: Break up the User Manual!

PostWed Nov 06, 2019 8:46 pm

Mel Matsuoka wrote:While the technical presentation of the documentation leaves much to be desired, the quality of its content is unassailable, and it's insulting to imply otherwise.


I don't care about the quality of the writing if I the information in incorrect, outdated, or missing. I'm not reading a 3000 page novel for entertainment, I need to find information, and the style of writing is meaningless.
Chad Capeland
Indicated, LLC
www.floweffects.com
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostWed Nov 06, 2019 9:03 pm

Chad Capeland wrote:I don't care about the quality of the writing if I the information in incorrect, outdated, or missing.


While I don't disagree that there is sometimes outdated and even incorrect material in the manual (as is often the case with massive software applications like Resolve), I've never found it to be lacking enough to dismiss it entirely as a "bad" manual.

I'm genuinely curious which specific information you've found to be "incorrect, outdated, or missing" that motivates your dismissive anger towards the manual?
Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostThu Nov 07, 2019 4:09 pm

Mel Matsuoka wrote:Please explain to me how a user would quickly find search results for information on using "Mattes" in the Color Page, without having to manually sift through dozens of other search results where the "Mattes" in question are referring specifically to Fusion?


Open the Bookmarks, go to the Color section, start your Search from there.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostThu Nov 07, 2019 4:11 pm

Mel Matsuoka wrote:Are you seriously suggesting that scrolling down to the "page bottom" of each search result in order to grok the Chapter name is a good, efficient way of finding the information you need quickly?


I'm saying your monitor should be large enough to display the whole page at once and still read it comfortably.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostThu Nov 07, 2019 4:15 pm

Mel Matsuoka wrote:What you apparently don't seem to grasp is that there are always better ways of doing things


I understand the concept. I just don't think this idea qualifies as such. That's why my first post was "I would vote no on this if BMD were to ask." I don't actually have any veto authority here. Just a viewpoint.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostThu Nov 07, 2019 4:16 pm

John Paines wrote:A comprehensive index would also be extremely helpful.


Now that I believe qualifies as a "better way".
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

wd60xxx

  • Posts: 58
  • Joined: Thu Jun 20, 2019 10:46 pm
  • Real Name: David Southam

Re: Break up the User Manual!

PostThu Nov 07, 2019 7:27 pm

Just wanted to thank Mel and Marc for their skillful posts on this subject, and sorry to have started another similar thread.
Offline

Justine Robilliard

  • Posts: 170
  • Joined: Thu Apr 10, 2014 1:00 pm

Re: Break up the User Manual!

PostSat Nov 09, 2019 4:32 am

Why not have both? What is wrong with having 6 part pdf's and 1 3000 page pdf?
Having the file in parts makes a lot of sense, and so does a single file..

When you bought Final Cut Pro 2, it came in a box, that weighed a ton, a dozen dvd roms, and 4000 pages over a span of books, and a pdf somewhere... Apple printed out every page of Final Cut Studio...And it was massively comprehensive, if you read from cover to cover, you should have been awarded a PHD!!!

I cannot see the harm in splitting for those that want a sectioned system, and keeping a full unchanged version...both are useful...
Offline

Hendrik Proosa

  • Posts: 3015
  • Joined: Wed Aug 22, 2012 6:53 am
  • Location: Estonia

Re: Break up the User Manual!

PostSat Nov 09, 2019 6:47 am

Computers used to come with instruction set manuals too. Time has moved on, hypertext was invented more than twenty years ago, so I'm not exactly following the locked pdf only logic, however many pieces it is split to. But what is still missing is a proper reference manual, what currently is provided is a user guide. What is the difference? User guide tells user what to do, reference manual tells what every piece of software is supposed to do.
I do stuff.
Offline
User avatar

PRESSRESET

  • Posts: 26
  • Joined: Mon Nov 11, 2019 9:53 pm
  • Real Name: Preston Allen

Re: Break up the User Manual!

PostMon Nov 11, 2019 11:44 pm

I don't want the PDF. Please move AWAY from the PDF!

I'd like to see them move into a Documentation tool that is available via a browser... this is far easier to maintain, and can be auto populated for updates by the developers as new features are added or maintained/changed. The PDF manual is actually fantastic vs other manuals, (overlapping and in some places skint on information in some points,) but the software features with ALL the products are moving SUPER fast, and things are changing rapidly.

Online Documentation is the way to go, and WAY easier to maintain. Even developers are able to submit requests to the manual maintainer team for updates to the manual or we as users can request updates and further information on features or mark things invalid for X version.

It also allows BMD to have a DIRT simple app that contains just an HTML browser that opens TO the manual so you can browse the manual on your tablet or phone.

Updating a PDF is 2010. We are almost in 2020.
Offline
User avatar

waltervolpatto

  • Posts: 10502
  • Joined: Thu Feb 07, 2013 5:07 pm
  • Location: 1146 North Las Palmas Ave. Hollywood, California 90038 USA

Re: Break up the User Manual!

PostTue Nov 12, 2019 8:36 pm

PRESSRESET wrote:I don't want the PDF. Please move AWAY from the PDF!

I'd like to see them move into a Documentation tool that is available via a browser... this is far easier to maintain, and can be auto populated for updates by the developers as new features are added or maintained/changed. The PDF manual is actually fantastic vs other manuals, (overlapping and in some places skint on information in some points,) but the software features with ALL the products are moving SUPER fast, and things are changing rapidly.

Online Documentation is the way to go, and WAY easier to maintain. Even developers are able to submit requests to the manual maintainer team for updates to the manual or we as users can request updates and further information on features or mark things invalid for X version.

It also allows BMD to have a DIRT simple app that contains just an HTML browser that opens TO the manual so you can browse the manual on your tablet or phone.

Updating a PDF is 2010. We are almost in 2020.


Unless you work in Hollywood where studios and MPAA restrictions and security force every machine that does production to be off grid permanently.

Not everybody in the world is 24/7 on the net.
W10-19043.1645- Supermicro MB C9X299-PGF - RAM 128GB CPU i9-10980XE 16c 4.3GHz (Oc) Water cooled
Decklink Studio 4K (12.3)
Resolve 18.5.1 / fusion studio 18
GPU 3090ti drivers 512.59 studio
Offline
User avatar

PRESSRESET

  • Posts: 26
  • Joined: Mon Nov 11, 2019 9:53 pm
  • Real Name: Preston Allen

Re: Break up the User Manual!

PostTue Nov 12, 2019 11:44 pm

waltervolpatto wrote:
Unless you work in Hollywood where studios and MPAA restrictions and security force every machine that does production to be off grid permanently.

Not everybody in the world is 24/7 on the net.


While I completely understand this sentiment, once the manual is built in Online Documentation, multiple types of documentation are easy to generate. Be it .PDF, LaTeX, .DOC, built into an APP, synced into Resolve locally on your machine... That's why every single large development software package uses online docs. It's easier to maintain throughout all levels of development and deployment, users of the documentation can flag things for revision, it's portable to any format, it's easy to version and control, and it's easy to deploy to offline users. Once you put it into a markdown type syntax, it's portable to any format via a single click of a button. We are in the future here. This is an editor built for the future. IMHO Use tools of the future, that are already proven tools for large software platforms. The reason why the .pdf keeps falling behind or lacks, is the ability to maintain a .PDF is extremely difficult as someone needs to manually update it. It's not a living document, but the software is, so having a living document makes the most sense. We still don't have proper scripting API documentation. It's just a readme text file. That can easily be absorbed into the full documentation set just by importing the classes and comments from the source. I'm sure they use some kind of repository for their software version control. Start there, use an auto builder to develop documentation from that and merge in the .PDF. It would take about 2 weeks of staffer time to do and get right, but the payoff is never having to maintain that static .PDF which is far more costly. Plus, if anyone wants a .PDF because they really want it, they can click the .PDF generate button and you get a version snapshot of the current documentation at that point in time that is marked as being snapshotted at that specific version/time.
Offline

Peter Cave

  • Posts: 3768
  • Joined: Thu Aug 23, 2012 6:45 am
  • Location: Melbourne, Australia

Re: Break up the User Manual!

PostWed Nov 13, 2019 4:48 am

I would prefer a single user manual with a proper index.
Resolve 18.6.5 Mac OSX 14.4 Sonoma
Mac Studio Max 32GB
Offline

Hendrik Proosa

  • Posts: 3015
  • Joined: Wed Aug 22, 2012 6:53 am
  • Location: Estonia

Re: Break up the User Manual!

PostWed Nov 13, 2019 10:45 am

For off-grid usage the common option is to provide whole hypertext help system as a downloadable archive.
I do stuff.
Offline

Justine Robilliard

  • Posts: 170
  • Joined: Thu Apr 10, 2014 1:00 pm

Re: Break up the User Manual!

PostWed Nov 13, 2019 10:54 am

One issue I have not seen discussed is that of 2nd or 3rd language speakers, for example you will have users that can converse in English, but use words incorrectly, but close enough to get the message across..

How do you translate this into a word or topic search, technical is hard enough for English 1st language speakers, how much harder for non 1st language speakers, I don't think BMD is going to translate into the top 50 languages spoken here in Africa...

A tough one no question, how do you create for a diverse set of users, users that have access to a network for data sharing, but not for browsing? Off line usage? What is better, pdf, html based? What options are there?

I have no idea what is better, or how many different types of data you can use to create a document that works both online and offline, that is searchable, and be able to mined for information for a wide range of English competency.
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostWed Nov 13, 2019 4:20 pm

Deleted.
Last edited by Jim Simon on Wed Nov 13, 2019 4:22 pm, edited 1 time in total.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Jim Simon

  • Posts: 29806
  • Joined: Fri Dec 23, 2016 1:47 am

Re: Break up the User Manual!

PostWed Nov 13, 2019 4:22 pm

PRESSRESET wrote:I'd like to see them move into a Documentation tool that is available via a browser.


Adobe does that. It's awful!

A single PDF with Index gets my vote as the best option.
My Biases:

You NEED training.
You NEED a desktop.
You NEED a calibrated (non-computer) display.
Offline

Dan Sherman

  • Posts: 1185
  • Joined: Fri Jul 01, 2016 11:07 pm

Re: Break up the User Manual!

PostWed Nov 13, 2019 5:59 pm

Jim Simon wrote:
PRESSRESET wrote:I'd like to see them move into a Documentation tool that is available via a browser.


Adobe does that. It's awful!

A single PDF with Index gets my vote as the best option.


That's because Adobe is piss poor at documenting everything. About a decade ago I had to write an application for work using their Flex framework. By the time the project was over I probably would have punched out the people that wrote the documentation if you stood them infront of me.
AMD 7950X | AMD 7900XTX (23.20.24) | DDR5-6000 CL30-40-40-96 2x32 GB | Multiple PCIe 4.0 X4 NVME | ASUS x670e HERO | Win 11 Pro 23H2 | Resolve Studio 18.6.5 B7
Offline
User avatar

PRESSRESET

  • Posts: 26
  • Joined: Mon Nov 11, 2019 9:53 pm
  • Real Name: Preston Allen

Re: Break up the User Manual!

PostThu Nov 14, 2019 7:59 pm

Jim Simon wrote:
PRESSRESET wrote:I'd like to see them move into a Documentation tool that is available via a browser.


Adobe does that. It's awful!

A single PDF with Index gets my vote as the best option.


+1 on Dan Sherman's reply about Adobe docs. That's not an issue with the system the docs are stored in, that's an issue with the documentation itself. The docs for Resolve IMHO aren't "bad". They are in some places incomplete or don't go as in depth as they potentially could and it feels like (from the outside here... having worked on large software development teams) that it's because it's a matter of resources that can be devoted to managing and updating the documentation. BMD has what? Under around 300 employees total? They could devote what? 25 at max to Resolve dev? They also do hardware dev and maintain their cameras and other software packages. LOL. No wonder they are merging Fusion and Fairlight. It merges the teams. That's a TINY team. Adobe has 21,000 employees. There are 100 employees alone that just work on Photoshop's CORE components. That doesn't even count all the outside stuff, supporting teams and the QA teams. So, I am suggesting tools that ease burden on developers, because the faster and easier the developers can roll the changes into documentation, the faster the documents get updated.
Offline

Trensharo

  • Posts: 447
  • Joined: Mon Jul 23, 2018 1:20 pm
  • Real Name: Nate Doucette

Re: Break up the User Manual!

PostSat Nov 16, 2019 4:29 am

Jim Simon wrote:
PRESSRESET wrote:I'd like to see them move into a Documentation tool that is available via a browser.


Adobe does that. It's awful!

A single PDF with Index gets my vote as the best option.

Lots of companies do it. I think Adobe does a decent job at it. The problem with that type of documentation is that if you don't have an internet connection, you can't reference it.

Unless the documentation is all local and you're just using the browser as a user interface...which I'm not particularly opposed to - especially if it allowed them to make the help more context-sensitive.

I wouldn't mind if they broke the documentation out into Modules.

I can't even upload the current one to Google Play Books anymore, and sometimes my query is specific to a specific page. This would make everything easier to get to.

Frankly, I'm hating the modern trend away from Context Sensitive Help files. I don't tend to find PDF documentation very accessible, or convenient when I need an answer on the spot (or have a question about a certain thing in the application).
Offline

Mel Matsuoka

  • Posts: 1179
  • Joined: Wed Aug 22, 2012 9:54 am
  • Location: Clarence, NY

Re: Break up the User Manual!

PostFri May 14, 2021 9:00 pm

As it turns out, the monolithic nature of the Resolve manual is completely intentional.

I was just listening to Alexis Van Hurkman's "DaVinci Resolve Q&A Happy Hour Episode 05", and he directly addressed Marc Wielage's wish for the manual to be broken up into multiple PDF files. He said that he intentionally made the decision for it to be a single PDF, because he didn't want people to have to manage multiple documentation files, especially for those who are on set and away from the internet, and forgot to download the appropriate manual for what they need to reference.

I'm not particularly convinced of this reasoning, as the PDF manual is already directly embedded in the application package (at least on macOS), and doesn't need to be downloaded first in order to open. But I'll take Alexis' word on this.

I'm sad that Alexis is no longer writing the Resolve documentation. For all its organizational faults, the Resolve manual is one of the best examples of technical documentation I've ever read.

(Skip to 1:26:41)

Resolve Studio 18.0.2 / Decklink Mini Monitor / 14" 2021 Macbook Pro Max (macOS 12.5.1, M1 Max) / 32GB RAM
Offline

Justine Robilliard

  • Posts: 170
  • Joined: Thu Apr 10, 2014 1:00 pm

Re: Break up the User Manual!

PostSat May 15, 2021 5:35 am

Thanks Mel for that great spot, interesting view from Alex about the intent, at one level it does make sense, and a split version as he points out might be a problem. To to troll through 3600 pages???

That has been my quest for a long time, having 1 giant 3600 page pdf is great, and so is having 5x dwarf files great, splitting the file into many parts makes it easier, I am assuming it would require a re-edit to create 5 new versions instead of just break up after chapter x or y..

Just curious as to the views...Last posted in 2019...talk about dust gathering...wow
Offline
User avatar

Charles Bennett

  • Posts: 6162
  • Joined: Sat Nov 05, 2016 11:55 am
  • Location: United Kingdom

Re: Break up the User Manual!

PostSat May 15, 2021 11:19 am

Though much smaller in size, the Pro Tools manual has a comprehensive index which makes it very user friendly. Just clicking on a page number takes you to that page. In this pic you can see how I/O Setup and Importing are dealt with. Would be nice if the Resolve manual had similar indexing.
Attachments
PT Reference Guide.jpg
PT Reference Guide.jpg (221.36 KiB) Viewed 4137 times
Resolve Studio 18.6.6 build 7
Dell XPS 8700 i7-4790, 24GB RAM, 2 x Evo 860 SSDs, GTX1060/6GB (546.01 Studio Driver), Win10 Home (22H2), Speed Editor, Faderport mk1, Eizo ColorEdge CS230 + BenQ GW2270 + Samsung SA200, Canon C100mk2, Zoom H2n.
Offline
User avatar

Marc Wielage

  • Posts: 10901
  • Joined: Fri Oct 18, 2013 2:46 am
  • Location: Hollywood, USA

Re: Break up the User Manual!

PostSat May 15, 2021 10:48 pm

Charles Bennett wrote:Though much smaller in size, the Pro Tools manual has a comprehensive index which makes it very user friendly. Just clicking on a page number takes you to that page. In this pic you can see how I/O Setup and Importing are dealt with. Would be nice if the Resolve manual had similar indexing.

Yes, the Pro Tools manual is a model on how to design a great manual that has a concise index with hyperlinks. But to put it in perspective, they've had almost 30 years of writing and refining that manual to get it to where it is today. I have all of the Resolve manuals going back to Version 6.0, and they've gotten much better (albeit much larger) is time goes on. 6.0 was only 303 pages long!

Here's the Resolve 6.0 cover:

Image

And here's what the GUI looked like back in 2006:

Image

Resolve has come a long, long way, and while we sometimes nitpick it to death here, it's amazing how much it's improved in the last 15 years.
marc wielage, csi • VP/color & workflow • chroma | hollywood

Return to DaVinci Resolve Feature Requests

Who is online

Users browsing this forum: No registered users and 15 guests