V11 documentation : always the same story
Hi,
I guess that, as usual, we'll have to wait several months until a PDF version of the user's guide be available and that it will eventually be of the same quality level as the previous PDF files, that is, unusable. With the price of a single C1 license, P1 could certainly purchase a good PDF generator.
I'm the kind of user who reads the documentation... when it exists. Clicking on "Download PDF" brings you to the nowhere land. The online help is not detailed enough. Just one example among so many : where do you find in the online guide information about soft proofing ? Isn't soft proofing a feature that all pros use ? And please don't tell me to use the Search feature on the Online Help page.
The documentation problem has been raised since version 8 as far as I'm concerned. No progress since then. A pity for a "Pro" software. When I was teaching software development, I always told my students that when a software has no decent documentation, only 50% of the job has been done.
I guess that, as usual, we'll have to wait several months until a PDF version of the user's guide be available and that it will eventually be of the same quality level as the previous PDF files, that is, unusable. With the price of a single C1 license, P1 could certainly purchase a good PDF generator.
I'm the kind of user who reads the documentation... when it exists. Clicking on "Download PDF" brings you to the nowhere land. The online help is not detailed enough. Just one example among so many : where do you find in the online guide information about soft proofing ? Isn't soft proofing a feature that all pros use ? And please don't tell me to use the Search feature on the Online Help page.
The documentation problem has been raised since version 8 as far as I'm concerned. No progress since then. A pity for a "Pro" software. When I was teaching software development, I always told my students that when a software has no decent documentation, only 50% of the job has been done.
0
-
Did you plan to write an user manual in french ?
Sometime it's really hard to found a function named in english in user manual but translated in french in the software.0 -
[quote="Samoreen" wrote:
Hi,
The documentation problem has been raised since version 8 as far as I'm concerned. No progress since then. A pity for a "Pro" software. When I was teaching software development, I always told my students that when a software has no decent documentation, only 50% of the job has been done.
Possibly true.
However, as sometimes illustrated by questions in this forum, people tend not to read documentation and if they do seem to have a way of not understanding it.
Over the years I have written quite a lot of User Guide type documentation and proof read a lot more produced by others.
When working with user in the field to whom this effort was dedicated it was quite clear that probably only 5% read any of it unless they were the project people responsible for making sure that the contracted "must have" terms and conditions for documentation was being satisfied. Just a pity that those same people had no task allocated to them to make sure that the people who needed to read the documentation actually did so. Indeed it would have been good if the client had made the documentation available to their staff - it did not happen in many cases.
At the "engineering level" - programmers cutting code and, more important in many situations, those coming and maintaining the code later, I could not agree more. Preferably with comments in the code.
It's another situation where the application of the principle, religiously applied by some individuals, can be eroded by those who as less complete in their approach. Even when embedded in a "Quality Control" assessment from some form of external Certification organisation.
I recently read some apparently very comprehensive documentation for a product. For a particular sort of procedure there was a 3 or 4 page step by step description. Great!
The procedure had about 20, maybe 30, variations. In many cases only one line was different. Each variation was presented separately on 3 or 4 pages.
If, as a project manager, you were training people who only needed one or two of the procedures and you want to make a specific reference point for them that might be useful. As a generic user manual it added pages and made the page and word count impressive but was not really very helpful for discovering areas of functionality in a wider context. In some cases that may be the only way to do it in reality. It's what I felt was needed when I started to user guides for business applications.
But in a business the software operations mean that users are often only working with a small part of the entire system.To be able to give each user just the relevant parts of the documentation pertinent to their job is possibly important.
For products like C1 I'm really not sure that works as well - especially in a "creative" rather than "standardised process" situation.
Of course, back in the day we were less afflicted with the curse of "agile" development .... 🤓0 -
[quote="SFA" wrote:
[quote="Samoreen" wrote:
If, as a project manager, you were training people who only needed one or two of the procedures and you want to make a specific reference point for them that might be useful. As a generic user manual it added pages and made the page and word count impressive but was not really very helpful for discovering areas of functionality in a wider context.
If at least all available features could be at least described, even if not accurately, I would already be happy. What is really not acceptable is when a menu or button command is not even mentioned in the help file. The example I gave is typical.0 -
[quote="SFA" wrote:
[quote="Samoreen" wrote:
If, as a project manager, you were training people who only needed one or two of the procedures and you want to make a specific reference point for them that might be useful. As a generic user manual it added pages and made the page and word count impressive but was not really very helpful for discovering areas of functionality in a wider context.
If at least all available features could be at least described, even if not accurately, I would already be happy. What is really not acceptable is when a menu or button command is not even mentioned in the help file. The example I gave is typical.0 -
The Proof profile example?
https://help.phaseone.com/en/CO11/Expor ... aspx#item5
The PDF download for V10 also mentions it under the same section - which as far as I recall is not changed from V10 when it was introduced.
I think the PDF versions of the documentation usually appear shortly after the release rather than at the same time.
For me the link to the On-line Help then provides a "Download PDF" option which takes me here.
https://www.phaseone.com/SupportMain/Ma ... tware.aspx
V11 is not yet listed but of course most of the V10 guide is relevant and the release notes outline what is different. The PDF file is fully searchable.
The "?" icons in the tools connect to relevant links for the tool. Click through to the next level for that tool.
So if you start on the Process Recipes tool the ? takes you to the summary collection pages for Process recipes and "View more information related to Process Recipes" gets to the expanded description. The third section of that describes proofing.
Or at least all of this works on a Windows system running Win 7 and allowing MS Internet Explorer to function. English version in my case - I can't easily comment on localisations. Nor how it might all function on a Mac.
HTH.
Grant0 -
I used to write product documentation for a living.
Documentation writers LOVE to write. And they write far too much. I remember seeing a 700-odd page book on using Microsoft Word V3. Crazy, no-one will read it.
The trick to good documentation, in my view, is to split it into two:
The second part tells you HOW to do something. This is equivalent to clicking the help icon on each tool, and I think CO is pretty good with that. It's detailed of course, and takes time. As an aside, I found that creating this documentation as part of the development phase was most useful. It shows the programmer exactly what has to happen, and it allows the designer to look at the object from the user's point of view, which results in good tweaks, sometimes small, sometimes large.
The first part is far more important, since in any event most people are happy to play with the software and discover how to use it. But the first part has to show you WHAT THE SOFTWARE CAN DO, and then point to WHERE you do it.
Software developers, designers, and documenters, know their product inside out. They live with it every day. They don't know how much they know, and they don't know how much users don't know. Actually, software companies do their products a huge disservice by simply not telling their users what their software can accomplish.
And the way to best achieve this is not to just enumerate tools or features. You need to EXPLAIN WHY. For example, you don't say you have layers. You say that as a user you may want to adjust part of the image one way, and another part another way. The sky is too bright, everything else is fine, how can you fix just the sky? And then show where you create layers, show a screen or two, but don't show how. Leave that for the other part.
I'm sure layers are well understood by many people, but you'd be surprised. The Color Editor is more unique, but you treat every feature and tool the same way. Lots of users haven't ever used levels and curves, even if they own Photoshop. Just lay it all out. Here is WHAT this software can do. Without any HOWS, it becomes a relatively short document, something you can read through without running the software, something that lets you see all the different possibilities. It makes you want to go and try it all out.
It's quick to produce this, it's easy to keep it up to date, and it becomes a GREAT marketing tool.
And for existing users, an equivalent what's new document, in the same format, is invaluable.
Like all writers, I've written too much 😄0 -
[quote="mikekatz" wrote:
I used to write product documentation for a living.
Documentation writers LOVE to write. And they write far too much. I remember seeing a 700-odd page book on using Microsoft Word V3. Crazy, no-one will read it.
The trick to good documentation, in my view, is to split it into two:
The second part tells you HOW to do something. This is equivalent to clicking the help icon on each tool, and I think CO is pretty good with that. It's detailed of course, and takes time. As an aside, I found that creating this documentation as part of the development phase was most useful. It shows the programmer exactly what has to happen, and it allows the designer to look at the object from the user's point of view, which results in good tweaks, sometimes small, sometimes large.
The first part is far more important, since in any event most people are happy to play with the software and discover how to use it. But the first part has to show you WHAT THE SOFTWARE CAN DO, and then point to WHERE you do it.
Software developers, designers, and documenters, know their product inside out. They live with it every day. They don't know how much they know, and they don't know how much users don't know. Actually, software companies do their products a huge disservice by simply not telling their users what their software can accomplish.
And the way to best achieve this is not to just enumerate tools or features. You need to EXPLAIN WHY. For example, you don't say you have layers. You say that as a user you may want to adjust part of the image one way, and another part another way. The sky is too bright, everything else is fine, how can you fix just the sky? And then show where you create layers, show a screen or two, but don't show how. Leave that for the other part.
I'm sure layers are well understood by many people, but you'd be surprised. The Color Editor is more unique, but you treat every feature and tool the same way. Lots of users haven't ever used levels and curves, even if they own Photoshop. Just lay it all out. Here is WHAT this software can do. Without any HOWS, it becomes a relatively short document, something you can read through without running the software, something that lets you see all the different possibilities. It makes you want to go and try it all out.
It's quick to produce this, it's easy to keep it up to date, and it becomes a GREAT marketing tool.
And for existing users, an equivalent what's new document, in the same format, is invaluable.
Like all writers, I've written too much 😄
Good post Mike.
I totally agree. I think the content already exists, at least in concept, for C1 but it may not be entirely obvious when users access it.
As a user you also owe it to yourself to have an investigative mind.
What tools are there available?
How might they be used?
How might I use them for my work?
Sounds interesting, let's try it.
OK, remember that possibility for future use - come back and learn the details at the time of need.
I find, and I know that some do and some don't, that once you have a good feel for the general approach of a product it becomes much easier to build more and more successful use simply by asking yourself - "which tools are likely to provide the functionality for me do this or that ..." And if you remember reading somewhere that it could be done, even if you did not dig into the details at the time, you are already half way to finding the solution.
On the other hand that approach can stop working if everything gets too complicated for a quite specific purpose in hand - as software bloat tends to do.
Grant0
Post ist für Kommentare geschlossen.
Kommentare
7 Kommentare