Lack of accurate documentation
Hi,
When I was teaching software development, I always told my students that a software without a complete and accurate documentation is not a finished product and therefore should not be delivered. Building the documentation is not a by-process and should not be done "after the fact". It's a part of the development process as well as coding. So when the software is ready, the documentation should be ready as well. Building the documentation during the development process is a guarantee for quality. Writing it after the fact is a guarantee for inaccuracy and incompleteness.
P1 is essentially targeting pros and advanced users. Their pricing is not particularly moderate. For that price, a complete documentation should be made available as soon as the software is available for sale. The current v9 documentation is from far not the documentation that C1 deserves. A couple of videos and a blog with some technical articles (often interesting, by the way) are not a replacement for a real and complete documentation. As a new C1 user, I'm very disappointed by this policy.
When I was teaching software development, I always told my students that a software without a complete and accurate documentation is not a finished product and therefore should not be delivered. Building the documentation is not a by-process and should not be done "after the fact". It's a part of the development process as well as coding. So when the software is ready, the documentation should be ready as well. Building the documentation during the development process is a guarantee for quality. Writing it after the fact is a guarantee for inaccuracy and incompleteness.
P1 is essentially targeting pros and advanced users. Their pricing is not particularly moderate. For that price, a complete documentation should be made available as soon as the software is available for sale. The current v9 documentation is from far not the documentation that C1 deserves. A couple of videos and a blog with some technical articles (often interesting, by the way) are not a replacement for a real and complete documentation. As a new C1 user, I'm very disappointed by this policy.
0
-
Based on your comment about "when I was teaching" suspect that you and I may be of a similar generation.
I entirely concur with your views.
However, the world may be a little more complicated these days and certainly seems to move faster year by year.
I doubt that the majority of new users from a more recent generation give a damn about documentation of any sort. I used to write User Guides that I know were never ready. Heck, it was difficult enough to get a customer project team to read and vaguely understand a specification for something they had said they wanted.
If you wait until someone have finalised some software, double check the accuracy of the documentation and then agree to the release of the product - the world will have moved on. There will be 10 new "must buy" camera bodies to support, 75 new ideas for "features" with 70 disappointed individuals whose best idea ever has not made the next sub-dot release since it was obviously going to be incredibly popular and the OS and hardware manufacturers will have moved the goalposts in opposite directions and then chosen a different game to play in the field.
All of that without even thinking about the special interests of the people involved with development decisions.
Nobody - except maybe you and me and one or two other old timer traditionalists - reads documentation. It's too much effort. Far easier to post a question on a forum, such as this one, and then "bump" after 10 minutes when no one has responded.
I often see several posts a day to which I resist responding "Why don't you just try it?" Isn't that what a creative mind, however limited it might be in the pantheon of artistic genius would do?
Tried that and still failed? Sure, come and post. Say "I tried that and failed." Then ask for help. One is likely to find all sorts of useful advise much of which could not possibly be included in a specific response in documentation because no one would ever try to read the resulting detailed text or if they did the answer would be hidden so deeply in the description it would likely be unrecognisable.
The last release of some successful business software I had been involved with from very early days was essentially both bug free and documentation perfect. User who transitioned to it did so very successfully. Questions were few. All answers were available in supporting documentation notably via searchable PDF files - quite early in the Adobe documentation success game.
From there on the application faded away and was gone within about 3 years. In effect all of that effort to force completeness and quality was an utter waste of time and resource.
But yes, I still agree with you. In an ideal world with ideal users full documentation, preferably online and updated daily with advisory communications to all users, would be a highly desirable state to achieve. Probably rather expensive however.
How many vendors are delivering such a service? I am especially interested to understand what the bigger players in the commercial business market try to achieve and how well it is funded by the new favourite revenue generation subscription model if you have an figures to point to.
I will admit that my interest in the answers lies outside the Capture One marketplace.
Grant0 -
Grant,
Globally, I agree with your statements. But I think that there must be a middle way between lacking documentation and perfect documentation. For example, the current documentation doesn't even have a reference section for the various menus available in C1.
Anyway, you're correct, I'm one of those old guys who read the documentation (when it exists) before using a software or a device. Maybe it's the reason why I find bugs so quickly 😄 .0 -
[quote="Samoreen" wrote:
A couple of videos and a blog with some technical articles (often interesting, by the way) are not a replacement for a real and complete documentation. As a new C1 user, I'm very disappointed by this policy.
I am wondering if you have clicked the "?" signs in the software?
If not, here's the link: http://help.phaseone.com/en/CO9/Introduction.aspx0 -
[quote="Christian Gruner" wrote:
[quote="Samoreen" wrote:
A couple of videos and a blog with some technical articles (often interesting, by the way) are not a replacement for a real and complete documentation. As a new C1 user, I'm very disappointed by this policy.
I am wondering if you have clicked the "?" signs in the software?
Christian,
Of course I have. I'm talking about "accurate" documentation. The online help system is not detailed enough and it has a lot of bugs which I have recently reported to the support team. Sometimes, clicking on a link in the v9 documentation brings you back to the v8 documentation (a behavior that one may not notice immediately), sometimes the "?" signs bring you to nowhere like in the Print dialog, and there are a lot of broken links in these pages.
Also, sections existing in the v8 documentation are missing in the v9 documentation. When a link in the v9 documentation brings me back to the v8 documentation, should I assume that the v8 documentation applies? And when a link in the v8 documentation brings me back to the v7 documentation, should I assume that the v7 documentation applies? To which documentation history level are we supposed to go back until we find the correct information?
Just to mention a few quirks among many others. And by the way, when you click on "Download PDF", well you now, there's nothing like a PDF file for v9. Any chance to get it one of these days?
So I repeat, C1 doesn't have the documentation it deserves and this has to be fixed. C1 is not donation ware. For the price paid, documentation should be fully available, tested and accurate.
Regards.0 -
[quote="Samoreen" wrote:
Sometimes, clicking on a link in the v9 documentation brings you back to the v8 documentation (a behavior that one may not notice immediately)
More about this...
Once you have clicked in the v9 doc on a link that brings you to a section of the v8 doc, the only thing that changes in the user's environment is the 9 being replaced with a 8 in the page subtitle (top left). So you usually don't notice that you are not in the relevant context. The user can then click on another section link and access v8 documentation while thinking he's reading v9 documentation. The same applies between v8 and v7, etc. So you find yourself reading documentation that is not relevant to the version of C1 you are using.
So one wonders whether these links are
- wrong links that have not been correctly updated (merely copied from the v8 doc).
- correct links bringing us to the v8 doc because the corresponding section in the v9 doc doesn't (yet?) exist (in which case there should be a way to return to the v9 doc - currently, the only way to directly switch back to the v9 doc once I have been misled to the v8 doc is to change the folder name in the address bar of the folder, replacing CO8 with CO9).
Which is which? This is rather messy to say the least.0 -
[quote="Samoreen" wrote:
[quote="Samoreen" wrote:
Sometimes, clicking on a link in the v9 documentation brings you back to the v8 documentation (a behavior that one may not notice immediately)
More about this...
Once you have clicked in the v9 doc on a link that brings you to a section of the v8 doc, the only thing that changes in the user's environment is the 9 being replaced with a 8 in the page subtitle (top left). So you usually don't notice that you are not in the relevant context. The user can then click on another section link and access v8 documentation while thinking he's reading v9 documentation. The same applies between v8 and v7, etc. So you find yourself reading documentation that is not relevant to the version of C1 you are using.
So one wonders whether these links are
- wrong links that have not been correctly updated (merely copied from the v8 doc).
- correct links bringing us to the v8 doc because the corresponding section in the v9 doc doesn't (yet?) exist (in which case there should be a way to return to the v9 doc - currently, the only way to directly switch back to the v9 doc once I have been misled to the v8 doc is to change the folder name in the address bar of the folder, replacing CO8 with CO9).
Which is which? This is rather messy to say the least.
There has very recently been quite a large effort to correct these links. Are you still able to find wrong links? If so, please don't hesitate to contact our Support.0 -
[quote="Christian Gruner" wrote:
There has very recently been quite a large effort to correct these links. Are you still able to find wrong links? If so, please don't hesitate to contact our Support.
Christian,
If we are still talking about links in v9 documentation leading to the v8 documentation, there are still a lot of them and they are easy to find. Just an example:
- Go to
- All the links in the very last paragraph of this page are linking to the v8 documentation.
And this is just one example for one single page. Almost every page in the documentation that has at the bottom of the page a paragraph referring to another section or that has a "Learn More" section has such links sending me back to the v8 documentation.
I have already given a few examples to the Support but I can't spend my time tracking all these errors. This is not my job. It should be easy to scan the source code of all the v9 documentation pages and to detect those containing at least one link to http://help.phaseone.com/en/CO8/... You'll find a lot of them.
This seems to be a very old problem since you have exactly the same issues in the v8 documentation.
Well, I'm sure that Grant will tell me that this is another proof that nobody reads the documentation and that this didn't start with v9 😁 .0 -
[quote="Samoreen" wrote:
Well, I'm sure that Grant will tell me that this is another proof that nobody reads the documentation and that this didn't start with v9 😁 .
Hehe.
Yep.
Should we also discuss the challenges of proofreading one's own documentation?
(Just for "fun")
🤬0 -
He, he looks like nobody reads documentation this days.
I've never noticed issues with ? buttons because I never used them.
Different generation, different approach to software 🤭0 -
[quote="Andriy.Okhrimets" wrote:
He, he looks like nobody reads documentation this days.
Different generation, different approach to software 🤭
Yes, it seems that people now prefer to spend even more, buying one or several books about the software instead of reading the documentation they have already paid for 😁 .0 -
[quote="Samoreen" wrote:
[quote="Samoreen" wrote:
Sometimes, clicking on a link in the v9 documentation brings you back to the v8 documentation (a behavior that one may not notice immediately)
More about this...
Once you have clicked in the v9 doc on a link that brings you to a section of the v8 doc, the only thing that changes in the user's environment is the 9 being replaced with a 8 in the page subtitle (top left). So you usually don't notice that you are not in the relevant context. The user can then click on another section link and access v8 documentation while thinking he's reading v9 documentation. The same applies between v8 and v7, etc. So you find yourself reading documentation that is not relevant to the version of C1 you are using.
Still not fixed after 9.1.0 -
[quote="Christian Gruner" wrote:
There has very recently been quite a large effort to correct these links. Are you still able to find wrong links? If so, please don't hesitate to contact our Support.
I'm not seeing any correction to this problem after now that 9.1 has been released.0 -
We have it on the to do list.
Right now we are updating the help for 9.1 (some sections completely re-written) and working on feedback from the "was this useful" form to target weak areas first.
Please bare with us.0 -
[quote="Jim_DK" wrote:
We have it on the to do list.
Right now we are updating the help for 9.1 (some sections completely re-written) and working on feedback from the "was this useful" form to target weak areas first.
Please bare with us.
Well, we have been patient. At this time the documentation for version 9 is still as buggy as it was when I opened an incident about this issue months ago. Broken links, mix up with version 8 and 7, lack of details, still no PDF, no translation in foreign languages ,... What are you doing P1? C1 is not a shareware created by a one-man software shop. You certainly remember the price we have to pay for a license? Do you? After all these months, not being able to provide a decent documentation for a software at that price level is certainly not very professional.
You seem to consider that software documentation is something that should be done "after the fact". A professional development team manages the production of the documentation in parallel with the production of the code itself. Otherwise, it's not possible to design a good contextual help. Documenting a software is not something that is done on the developer's spare time. It's a true part of the job. So I consider that I have paid for something that is not finished.
Really disappointed by this lack of professionalism (and not only about the documentation, by the way).0 -
pretty sure you could have explored C1 in the time spent posting 😂 0 -
[quote="Bobtographer" wrote:
pretty sure you could have explored C1 in the time spent posting 😂
Sorry but I'm the kind of guy who reads the documentation before starting to "explore" and play the "trial and error" game. I know it's a somewhat outdated behavior but I have been educated this way. I find it's a more effective and faster way of mastering a software. Of course, this assumes that the documentation is not buggy and misleading.
The software editors now tend to explain that documentation is no longer that useful because their applications are so easy to use. A couple of videos should do. This is plain wrong.0
Post is closed for comments.
Comments
16 comments