Documentation - Better Way to Report Problems

[Incredible_hand16B8]

Currently, the online documentation includes this dialog at the bottom of web page entries:

The "not really" button leads to this dialog:

This dialog is inadequate for addressing problems in documentation:

1. Entries are limited to 235 characters.

2. No images can be included.

3. No additional dialog with Adobe employees or other users is possible to clarify the issue.

4. If the problem is that no documentation exists for a feature, then its not possible to leave a comment on a page that doesn't exist.

A better means of documenting, discussing, and resolving documentation issues is necessary.

Current means of addressing documentation issues are completely inadequate. This is demonstrably true. Recent example (stretching back to reports in February 2023).

R.

 

[Incredible_hand16B8]

@jasondecker 

As another user I'll thank you for your thoughtful and useful note regarding the inadequacies Adobe continues to exhibit around communication with its paid users.

I've noted, inquired, prodded, and otherwise requested specific and general improvements, to little effect.  (one example). My experience has been that those Adobe employees who do see comments about documentation take a "not my job" approach, and those Adobe employees who are specifically responsible for documentation have never responded. The few actions that have resulted from such notes have been slow and only partly address issues.

Nonetheless, one can hope. I, for one, appreciate your effort.

@Kevin-Monahan(documentation issues)

R.

[R Neil Haugen]

Adobe's documentation has been an runnning discussion for a long, long time.

Mostly, their manuals have been created by a listing of some of the things that each "something" can do. But not covering all things it might do, and also not covered as part of various workflows, so ... the implications and other effects on different need's usage for any tool or effect, effectively aren't covered.

That's rather an important bit left out, isn't it?

And the comments that some of the employees say "not my job" ... yea, I've heard that. But when hearing that in in-person discussions ... it's clearly something they understand why it's a problem, but the company is very compartmentalized. So it's not that they wouldn't prefer better documentation, it's that ... well ... one department poking into another in most human organizations is not really ... welcomed ... is it?

I have talked with some who do work in the manual/documentation area. And that was frustrating, as they tend to see when they've not updated their docs as a problem, at least. BUT ... they couldn't seem to grasp the lack of discussions of the full use of the tools, as I list above, as something "failed" on their part.

They didn't even understand what I meant. So both myself and the staffer were standing there with very puzzled faces. THAT ... is frustrating.

And I have talked with a couple that did see the problem ... but were very circumspect about it getting fixed ... due to  ... um .... well, um, right?

I've had hopes since Alexis Van Hurkman joined their staff that this would improve. He was in charge of writing that MASSIVE, 4,000 page manual for Resolve. Which is both awesome and ... difficult to use. It's huge, it covers SO many of the "in X do this, for Y do this, for Z use Q tool on page 3,234" things ... but ... there are two major noted problems with that tome.

1) No index! ... yea, that's a stunner.

2) WAY too many things have specific "DR" naming ... like we all know "masks" everywhere else are called "power windows" in DR. But there are a lot of things like that, and so you can actually read through the section you needed without realizing it at times.

Finally, the BEST documentation in Pr's suite of docs is the Long Form guide masterminded/written by Jarle Leirpoll. Whether any Pr user ever does any long form work, they should read this for the incredible use information from setting up computers through multicam and other things.

I'm including the Productions doc, because that's also better than anything else.

Premiere Pro Productions Introduction

Using Productions in Premiere Pro

Adobe Long-form and Episodic Best Practices Guide 

Jarle’s blog expansion of the pdf Multicam section: Premiere Pro Multicam

[Kevin-Monahan]

Hello @Incredible_hand16B8  and @R Neil Haugen,

Your feedback is appreciated. Thanks.

At the bottom of each Helpx page is a feedback option. Please make your suggestions there, if you don't mind. According to the docs team, that is the best method to provide feedback.

I would happily pass along any other feedback you might have for them.

Thanks,

Kevin

[Kevin-Monahan]

Hello @R Neil Haugen,

I've had hopes since Alexis Van Hurkman joined their staff that this would improve. He was in charge of writing that MASSIVE, 4,000 page manual for Resolve.

1) No index! ... yea, that's a stunner.

Alexis also helped write the documentation for Apple Final Cut Pro, which I also worked on a bit after his tenure. Alexis came in the Adobe realm via Frame.io, not Resolve. He didn't do documentation there and isn't working on Adobe documentation at all. Sorry for the let down.

Since the Helpx user guide is no longer a "book," it is more difficult to create an index and that was dropped many years ago for business reasons (creating a "book" vs. a content management system, as it currently stands).

The documentation team is working hard on a new look for help. I hope you like it when you get to see it.

Cheers,
Kevin

[R Neil Haugen]

Kevin,

I think a significant section of the user base would appreciate any great revisions to the "manual" system. That Long Form doc, and the Productions docs, were significantly more useful for users than the prototypical Premiere Pro information document. I hope those are the model for informational docs going forward.

The "standard" Premiere Help documentation has been primarily a straightforward listing of the basic function of the ... buttons? ... of the app. But this does not necessarily cover the use cases for those buttons. And certainly doesn't cover the implications of using X to do Y. With the accompanying further options and limitations.

It's that "down the line" information ... such as what and why the Merge Clips does compared to Multicam syncing ... that is so needed. And where the Long Form doc was so splendid.

In the past, I've suggested that say Jarle or Christine ... or preferably both! ... should be involved in the design and creation of the manual/help docs system. It would be the involvement of people like those two that would lift the docs to something we'd love to see.

[Incredible_hand16B8]

Kevin,

@Kevin-Monahan 

While I appreciate your consideration in making this its own forum post, it's unfortunate you would then suggest a "feedback option" that I specifically gave as an example problem. It's linked right there in what is now the original post of this thread. Follow the link - I've carefully listed just 4 of the issues with this current system. (If you're trying to say here that "Adobe is paying attention", you've demonstrated quite the opposite.)

To be clear:

The lack of a robust feedback mechanism is one of the many apects of Adobe's poor communication.

"The documentation team is working hard on a new look for help."

The "look" of the documention is the least of the issues.

Here's a place to start: what commitment is Adobe willing to make to users about documentation? What should users expect as part of Adobe's package, for which they pay Adobe every month?

R.

[Kevin-Monahan]

Hi there @Incredible_hand16B8,

Thanks for the response on the documentation and for reporting errors and shortcomings with it.

While I appreciate your consideration in making this its own forum post, it's unfortunate you would then suggest a "feedback option" that I specifically gave as an example problem.

I see what you're saying. Thanks for pointing me to the bug report that you already filed. Let's move this conversation to that bug report and see if we can get some solutions to your points.

Thanks!
Kevin

[Kevin-Monahan]

Hello @Incredible_hand16B8,

I read your bug report. Thanks for making it. You have some valid points. I will ensure an internal bug is filed on the documentation addressing the issues you listed with the documentation feedback mechanism.

Thank You,

Kevin

[Kevin-Monahan]

Hello @Incredible_hand16B8,

I appreciate you filing this bug. The shortcomings you noted are essential to address. I believe they can be fixed, but it may take some time. I am sorry about that.

This dialog is inadequate for addressing problems in documentation:

1. Entries are limited to 235 characters.

2. No images can be included.

I am pretty sure that the team can implement these UI requests. I also see these as crucial. One should have the same options as one for a forum post. Helpx and our forum platforms are different, so they might need additional engineering to add those features. I can help you advocate for these additions.

3. No additional dialog with Adobe employees or other users is possible to clarify the issue.

It is disappointing that no representatives from the docs team are here triaging posts that affect the documentation. I would love to see that team return to the forums as they once did. Previously, a docs lead would seek out potential bugs in forum posts to improve documentation in that area of the article. I would love to see a return to that kind of interaction. I will talk to my manager about this directive.

4. If the problem is that no documentation exists for a feature, then its not possible to leave a comment on a page that doesn't exist.

We will need to file a bug for any features that are not listed in the documentation. Otherwise, we could figure out how to address this problem, perhaps via these forums or with our experts program.

As an aside, our Adobe Experts are helping by pointing out documentation errors. They are our partners in improving documentation. I will send you a PM about that.

Thanks again for filing this bug.

Cheers,
Kevin

[Incredible_hand16B8]

I was encouraged by Kevin Monahan’s response to a current post about problems with Adobe’s documentation. He broke out the discussion, merged it with a post about documentation problems, and responded to the points I’d raised.

Unfortunately, he is not part of the “documentation team”, so we can only hope what the effect will be.

I thought I’d collect here a few of the more pressing issues a problems around Adobe documentation and support which have remained unaddressed.

1. Adobe documentation is false and outdated.

There are many examples of this. Here's a recent one.

2. Adobe has no documentation for the versions of Premiere Pro it commits to supporting.
Link

3. Adobe documentation requires a better way to report problems.
Link (this is the post mentioned in passing above)

4. Adobe does not clearly explain or maintain its “Known Issues” page.
Link and Link

5. The support purpose / limits of these forums remain ambiguous to users.

Link

R.

@Kevin-Monahan 

(documentation issues)

[Kevin-Monahan]

Hello @Incredible_hand16B8,

Thanks for these comments.

My experience has been that those Adobe employees who do see comments about documentation take a "not my job" approach, and those Adobe employees who are specifically responsible for documentation have never responded. The few actions that have resulted from such notes have been slow and only partly address issues.urrently, the online documentation includes this dialog at the bottom of web page entries:

I'm sorry that the support team's forum interactions are inadequate for addressing documentation issues. We need someone from the documentation team to address those issues directly so that our team can focus on troubleshooting.

As your advocate here, I have requested that a representative from docs be in forums and on social in the past and will continue to do so. That team is very busy, so something would have to change there from Adobe. I hope that the management can help fill that gap.

Thanks,
Kevin

[Kevin-Monahan]

Hi @Incredible_hand16B8

I wanted to address a couple more of your points.

"The documentation team is working hard on a new look for help."

The "look" of the documention is the least of the issues.

They are changing the look and feel, but also reorganizing the content so there fewer articles are overly long. It should help users.

What commitment is Adobe willing to make to users about documentation? What should users expect as part of Adobe's package, for which they pay Adobe every month?

I will try to get a manager to speak to this.

Thanks,
Kevin

[R Neil Haugen]

I would definitely love to see their entire documentation system upgraded also.