One of the challenges in my daily work is balancing "automation" and authentically trusting that the software I use (Confluence) will do what I want it to do when I use it the way their documentation tells me to use it. For example, their documentation told me that I could generate a PDF from a Confluence site. Their documentation is correct as the functionality to generate a PDF *does* exist.
What the documentation doesn't tell you is that you can't trust the result of the functionality. I did not glance at any other pages in this PDF. I found the following examples and realized I had content for a blog post. I immediately realized that a promise wasn't broken to the user. The documentation promises that the functionality to generate a PDF from your Confluence site is present. Definitely, that promise is kept. What the documentation doesn't do, though, is tell you that you should spot check the generated output for issues.
I spent less than 5 minutes looking at the content and I found issues. Professional documentation does not have dumb issues. Freely, I admit "professional documentation" is a judgment call so maybe my opposition to how these pages look and read is off-base. That said, I'm not wrong about this. Any professional writer or person that works with content that honestly believes the following are examples of "professional documentation" are flat-out wrong. But that's just my opinion so I could be wrong. Except I'm not. Here's the examples:
- Why is the heading row for this table on the previous page? At the bottom of the same page, a graphic doesn't display and, if it did, it appears as though the graphic would be cut off as it extends beyond the page margin.
- On the very next page, where is the graphic at the top of the page?
No comments:
Post a Comment