Creating the Useful Sidebar

There are many styles of writing employed for technical writing. Each style has specific benefits and today’s blog post won’t delve into them. However, many of these styles rely on the sidebar to add interest to the writing.

A problem occurs when an author seeks to present only facts as part of any written piece. Readers can find facts on the Internet. What readers can’t easily find is the specific viewpoint that an author presents, which includes supplementary materials in the form of sidebars. A sidebar adds interest to the writing, but more importantly, it provides background material that augments the topic at hand. For example, when discussing smartphone hardware, a sidebar that provides a brief overview of the communication technologies employed by that hardware can prove useful to the reader. The radio frequency transmission isn’t part of the main topic and some would argue that discussing it doesn’t belong at all in a pure hardware discussion, but the addition of that supplementary material is essential to the piece as a whole. It helps present a particular view of the technology that the reader wouldn’t otherwise receive.

Sidebars shouldn’t become a main topic. A good sidebar is at least one long paragraph, but more commonly two or three paragraphs. Never allow a sidebar to consume more than a page of text. For example, a two or three paragraph overview of the history of a technology is useful—a discourse that spans multiple pages is overkill unless the author is trying to make a particular point (in which case, the discussion should appear in the topic proper).

Depending on the sidebar content, you can include bulleted lists and numbered steps. A sidebar should never include graphics unless the book style accommodates such an addition (which is rare). The idea is not to detract from the piece as a whole, but rather augment it in a specific way—to help direct the reader’s attention in a specific manner. Using visual styles and white space correctly help make the sidebar attractive.

Many authors forget the need to evoke an emotional response in any sort of writing, including technical writing. In making a point, the author needs to express the idea fully by making an emotional appeal. A sidebar can perform this task nicely without creating distractions in the overall writing flow. For example, a piece about implementing accessibility features in an application can include a sidebar that contains a case study about the effects of such an implementation on a specific person or within a real world environment. The point is to help the reader understand the implications of a technology and make its use imperative.

Sidebars are an essential tool in the creation of a usable piece of writing that helps a reader understand a topic in ways that many factual Internet pieces can’t. Using sidebars effectively makes your writing better and more appealing. More importantly, a sidebar presents a unique view that the reader identifies with you as an author and sets your style of writing apart from that of other authors. Let me know your thoughts about sidebars at John@JohnMuellerBooks.com.

 

 

Security for Web Developers Released!

My Security for Web Developers book is released and ready for your review! I’m really excited about this book because I was able to explore security in a number of new ways. In addition, I had more technical editor support than just about any other book I’ve written and benefited from the insights of a larger than usual number of beta readers as well. Of course, the success of this book depends on you, the reader, and what I really want to hear is from you. What do you think about this latest book? Do you have any questions about it? Please feel free to contact me about it at John@JohnMuellerBooks.com.

Of course, I’m sure you want to know more about the book before you buy it. Amazon has the usual write-up, which is helpful, but you can also find insights in the beta reader request for this book. Make sure you also check out the blog posts that are already available for this book in the Security for Web Developers category. These value added posts will help you better understand what the book has to offer. More importantly, you get a better idea of what my writing style is like and whether it matches your needs by reading these posts.

Make sure you also get the source code for this book from the O’Reilly site. I highly recommend using the downloadable source, rather than type the code by hand. Typing the code by hand often leads to errors that reduces your ability to learn really cool new techniques. If you encounter errors with the downloaded source, make sure you have the source code placed correctly on your system. When you get to the O’Reilly download page you also find links for viewing the Catalog Page for this book and reporting Errata.

Have fun with my latest book! I’m really looking forward to hearing your comments. Thank you, in advance, for your continued support.

 

Build Your Own PC on a Budget Released!

I’ve been building my own computers for many years now. In fact, except for that first PC1 that I purchased many years ago from a friend (and modified until it finally died), I don’t know that I’ve ever purchased a computer for myself that was ready to run the moment it arrived on my doorstep because there is just something so amazing about putting the hardware together, installing the operating system, and seeing it boot for the first time. Many industry pundits say that the desktop PC is dead—replaced by laptops, notebooks, and even smartphones. It’s true that you can perform many computer tasks using these other systems and that many people will never need anything more, but for those of us who truly indulge our inner geek, nothing beats a custom built computer that is literally packed with the best technology available. It’s for those of us who need to satisfy the inner geek that I wrote Build Your Own PC on a Budget.

Of course, if you’re going to take the time and effort to build your own PC, you want it to precisely meet your needs and you want to get a deal on it. Normally, the systems I build for myself run about $2,500.00. I want high end graphics, lots of memory, speedy hard drives, and the best processors. I want a system that provides the maximum in expansion potential and promises a long lifespan. However, that’s me. For this book I wanted to create a computer system with more reasonable goals, so I designed a system around a $750 budget. The results are nothing less than incredible. What I ended up with was a moderately high end system that any gamer would like to have. The system focused on graphics capability so that the person receiving it would be able to work with images with a high degree of accuracy. In addition, this system has all the latest connectivity options, including both Bluetooth and Wi-Fi. In short, this is a great workstation and a good gaming system.

Build Your Own PC on a Budget uses this example system throughout to discuss principles. That’s right, the book actually follows the process of building this PC. However, it goes much further. I provide you with guidance on how you can modify this design to meet your specific needs. The question that this book answers most often is how to obtain the PC that you need and want, rather that settle for the PC that someone else designed to sell quickly to meet the needs of most people. You’re special, so you deserve a special PC. That’s what this book is all about.

One of the things that I strove for when putting this book together is clear photographs. Other books that I tried using when I first started building my own PCs often had muddy pictures that proved nearly useless. Pegg Conderman, my photographer for this book, went the extra mile in ensuring that the photos were absolutely clear. (You should have seen the contortions she went through to obtain this goal). I think you’ll agree that the photos really do set this book apart and make it the ultimate in usability.

If you have a strong desire to satisfy your inner geek, this is the book for you. I take you through the process step-by-step. Please let me know about your questions and concerns for this book at John@JohnMuellerBooks.com. As with all my books, I want you to be truly happy with the results you get from this book.

 

Reviews, Darned Reviews, and Statistics

A friend recently pointed me toward an article entitled, “Users who post ‘fake’ Amazon reviews could end up in court.” I’ve known for a long time that some authors do pay to get positive reviews for their books posted. In fact, some authors stoop to paying for negative reviews of competing works as well. Even though the actual technique used for cheating on reviews has changed, falsifying reviews is an age old problem. As the Romans might have said, caveat lector (let the reader beware). If there is a way to cheat at something, someone will most certainly find it and use it to gain a competitive advantage. Amazon and other online stores are quite probably fighting a losing battle, much as RIAA has in trying to get people to actually purchase their music (see Odd Fallout of Digital Millennium Copyright Act (DMCA) for a discussion of the ramifications of IP theft). The point is that some of those reviews you’ve been reading are written by people who are paid to provide either a glowing review of the owner’s product or lambaste a competitor’s product.

Of course, it’s important to understand the reasoning behind the publication of false reviews. The obvious reason is to gain endorsements that will likely result in better sales. However, that reason is actually too simple. At the bottom of everything is the use of statistics for all sorts of purposes today, including the ordering of items on sales sites. In many cases, the art of selling comes down to being the first seller on the list and having a price low enough that it’s not worth looking at the competitors. Consequently, sales often hinge on getting good statistics, rather than producing a good product. False reviews help achieve that goal.

I’ve spent a good deal of time emphasizing the true role of reviews in making a purchase. A review, any review you read, even mine, is someone’s opinion. When someone’s opinion tends to match your own, then reading the review could help you make a good buying decision. Likewise, if you know that someone’s opinion tends to run counter to your own, then a product they didn’t like may be just what you want. Reviews are useful decision making tools when viewed in the proper light. It’s important not to let a review blind you to what the reviewer is saying or to the benefits and costs of obtaining particular products.

Ferreting out false reviews can be hard, but it’s possible to weed out many of them. Reviews that seem too good or too dire to be true, probably are fakes. Few products get everything right. Likewise, even fewer products get everything wrong. Someone produces a product in the hope of making sales, so creating one that is so horrid as to be completely useless is rare (it does happen though and there are legal measures in place to deal with these incidences).

Looking for details in the review, as well as information that is likely false is also important. Some people will write a review without ever having actually used the product. You can’t review a product that you haven’t tried. When you read a review here, you can be sure that I’ve tried out every feature (unless otherwise noted). Of course, I’m also not running a test lab, so my opinion is based on my product usage—you might use the product in a different manner or in a different environment (always read the review thoroughly).

As you look for potential products to buy online, remember to take those reviews with a grain of salt. Look for reviews that are obviously false and ignore them. Make up your own mind based on experiences you’ve had with the vendor in the past or with similar products. Reviews don’t reduce your need to remain diligent in making smart purchases. Remember those Romans of old, caveat lector!

 

Review of Jamie Collins’ Mystical Adventures: Ninelands

There aren’t as many gentle books today as young readers really need. Most of the books out there today seem determined to teach the young reader about all of the ills of life. In doing so, they often rob the child of his or her childhood. Jamie Collins’ Mystical Adventures: Ninelands (Volume 1) is a gentle story, meant to nourish the young reader’s creativity and provide good entertainment. It’s a delightful story that ties together many childhood characters: Santa Claus, Easter Bunny, and Tooth Fairy. The idea is that all of these characters are elves and somehow associated with Ninelands. Santa actually appears twice in the book and the latter mention adds to the Santa Claus saga. It’s the kind of story that builds a little on what the reader already knows and then adds to it.

The book is theoretically targeted toward the middle school reader and probably hits the mark from a reading grade level. However, this really isn’t the sort of story a middle school reader would enjoy reading—it isn’t a Harry Potter type story (except that both stories involve the use of magic). For example, the protagonists never really go on any sort of adventure or do anything of note except to explore (with help the help of their mentor) this new place. Yes, there is an attack, but the Alvar patrol (the equivalent of the Ninelands military) thwarts the attack, so the characters really aren’t in any danger. Ninelands will appeal more to a younger, early grade school, reader. The manner in which the book is written, the topics discussed, and the overall tone will make a younger reader feel an almost parental comfort during the reading of the story. It’s a story that offers security—throughout the story the author describes the various security measures in place to keep the characters safe.

This is a fanciful book and exceptionally creative. Characters travel around on spoons and within beams of light. They have snake guardians and magic crystals for communication and other needs. Even though the descriptive text lags terribly for the first quarter of the book, the remainder of the book more than makes up for any deficit. A reader is immersed in a world of wonder—of plants that play games and cats that talk. The one glaring omission is a good description of the main character, Jamie. The book never tells the reader what Jamie looks like to any real degree, so it’s hard to draw a mental image of him.

There are also mentions of things that don’t really get used in the book. The problem is that they’re more distracting than helpful in moving the story along. For example, Jamie plays with a dough boy, but the dough boy is never explained and the reader is left wondering precisely how the dough boy comes into play. The dough boy simply is there, probably a product of magic, but the book never says that this is the case, even at the end when the dough boy makes another appearance. Introducing an object, such as the dough boy, should help move the story along in some way.

The children do make a couple of decisions on their own, such as exploring the attic. Still, everything is immersed in an authoritarian environment. Children are constantly reminded of the rules and they always agree to follow them. Little goes on of an adventurous sort and the well behaved children never really do anything on their own. It’s a world that a younger child would enjoy, but an older child would find constraining to an extreme. Even the clown-like mentor, Minkel, takes on an authoritarian air for much of the book (despite spending a considerable amount of time dancing, which also makes him hard to take seriously).

Believability is stretched a little when Mike and Abby, Jamie’s friends, are told they’ll perform a subordinate role to their friend and they simply accept it without so much as a groan. In fact, they seem quite delighted to help their friend. Younger children love to exist in this sort of world, where there is no selfishness and everyone agrees with everyone else. It’s a supportive kind of view that doesn’t exist in the real world. A book for a middle school reader would be more realistic—Mike and Abby would complain, at least a little, and Jamie would complain a bit more about having to allow his little sister, Megan, help.

Some elements of the book do become annoying. The children spend so much time giving high fives and thumbs up in some areas of the book that it’s hard to believe they get anything accomplished. There is nary a frown mentioned in the book, but people are constantly grinning, smiling, and laughing. It is an exceptionally supportive kind of a book, but in some regards, the author goes too far and it’s easy for the reader to become distracted. In some respects, the book needs to feel a little more natural—a little more like the real world—in order to be believable.

There are some areas of the book where there is also a lot of repetition. The plot slows down to a crawl and sometimes stops altogether. The children stop to gawk at some new attraction and Minkel tells them about it, even if the children haven’t asked anything yet. Then come the rules, more rules, and still more rules beyond that. The children always agree to follow the rules, even if they’ve heard the same rules for the tenth time. Again, it’s the sort of environment that a younger child would enjoy, but I can hear a middle school reader screaming in frustration at some points in the book.

Is Ninelands a good book? Actually, it’s a really good book if you’re in the lower grades of grade school and have someone to read it to you. The fanciful world is quite appealing and I can see younger children getting quite caught up in it. After the first quarter of the book, the level of description really is quite good and I can see it helping the younger reader create mental images of what this wonderful world must be like. I really like the fact that this book doesn’t repeat the same tired vistas found in many other books—there are surprises and new things to explore. It’s the sort of book that a younger child will want read more than once because you really can’t get everything out of the text with just one reading. If you have a younger reader, you really do want to explore Ninelands because it’s fascinating place to visit.

 

Odd Fallout of Digital Millennium Copyright Act (DMCA)

Laws generally help define correct behavior when there is a difference of opinion between groups of people. They do things like ensure public health and safety. After all, when everyone agrees that certain behavior is acceptable (or unacceptable), you rarely see a law about it. Most laws also free people from the whims of government by providing a rule upon which to base decisions of whether someone is law abiding or not (the requirement to prove guilt, rather than innocence).

The context of an act usually comes into play. Stealing Intellectual Property (IP) is one of those areas in which there is a difference of opinion and context most definitely comes into play. There is a group on one side that says all information wants be free and that there is no such thing as stealing IP. This group is represented by people who download music or other forms of media without paying for it and feel the act is perfectly acceptable. On the other side is a group the vigorously defends IP, even when there isn’t a good reason to do so. This group is represented by organizations such as the Recording Industry Association of America (RIAA). Of course, artists and consumers alike are stuck in the middle between these two warring parties.

A law is considered fair and good when it represents the interests of as many parties as possible in an equitable manner. Over the years I’ve read about the truly odd fallout from the DMCA. For example, the RIAA suing a dead grandmother is an example of the sort of negative publicity that tends not to produce a desirable reaction when the goal is to get people to actually buy the music they want to hear. Of course, you’ve read about my viewpoint on IP a number of times. However, the fact of the matter is that publishers are slowly losing ground because the majority of people are ill-informed as to the need to buy IP and those who do know have decided that getting free IP for as long as they can is the only consideration. Most authors and artists (myself included) are starting to move toward means of earning a living that don’t involve fighting with customers over who should pay.

Unfortunately, the fight over IP is one of those things that just won’t go away because you want it to. I recently read an interesting InfoWorld article, Copyright act could make it illegal to repair your own car, that has me thinking of future stories in the news about Ford hauling dead grandmothers into court over repairs done without the consent of their local Ford dealer. The fact of the matter is that the DMCA is a bad law that represents only one side of the dispute—those who stand to make a huge profit from IP. Until the consumer is involved in the process and the voices of radical elements are heard, you can be sure that people will continue to ignore their rights and responsibilities when it comes to IP.

What do you see as the future of IP? The current situation isn’t sustainable. Authors and artists of all types need to earn a living just like everyone else. Someone has to pay for the IP or the people producing it will decide to do something else to meet their financial obligations (possibly creating lower quality and substantially less IP during their off hours). At the same time, consumers should be free to use the materials they purchased in any reasonable manner they see fit. If you buy one of my books, I guarantee that I’m not going to use the DMCA to haul you into court for marking it up or using it in a manner consistent with fair use laws. I’d like to get your feedback at John@JohnMuellerBooks.com.

 

Selecting a Computer Book

Readers contact me on a regular basis about selecting a computer book. I often think they want a precise recommendation from me (and some do ask me to provide a specific recommendation). However, I can’t choose a book for you or any other reader for a number of reasons. Most important of all, I don’t know how you learn. There are other issues too. For example, I can’t always guess from the e-mail precisely how you intend to use the book or what sort of information you need from it. In short, my best guess probably won’t be good enough.

Originally, I tried to handle the situation by providing a blog post entitled, “Techniques for Choosing a Technical Book.” The blog post worked well for a while, but it still doesn’t really answer reader needs. For example, readers would often act oddly if I didn’t recommend one of my own books, even though I knew from the reader query that my book would only solve part of their need and there was a better option out there. (Part of creating a book proposal is to look at the competition in depth and determine how your book will fill a niche that the competition doesn’t. I try to be honest with readers in this regard so that when they do buy a book, they’re happy with the purchase.) With this in mind, I wrote a series of three articles that examines the whole question of selecting a computer book in significantly more detail:

The goal of these three articles is to provide you with the best possible information about selecting and using a computer book. The thing I’ve noticed most often when I receive complaint e-mails is that even when a reader does select a truly usable computer book, sometimes they don’t get the most out of it. A purchase is only as good as the value you receive from it. These articles are designed to increase your satisfaction by helping you use the books more effectively.

Choosing and then using a computer book effectively will help you gain new marketable skills and insights into the computer industry. Overall, it’s my goal to help you earn more money or live a better life when I write a computer book. In other words, my goal is to help you gain something of value—something that you can later say improved your life in some way. Of course, I’m always refining my skills and choosing new techniques based on reader needs at any given time. That’s why I always want to hear from you at John@JohnMuellerBooks.com.

 

Perfect Love (Reposted)

I had a number of requests to post this poem again for Valentine’s Day. It’s my hope that you find perfect love during this Valentine’s Day celebration.

Perfect love casts out my fear.
Keep your perfect love so near
that I never fear again.
Perfect love for you attain,
‘til my heart with love is filled
and my spirit never chilled.

All around the world I see,
how a perfect love could be,
an answer for mankind’s woes,
when hatred and evil flows,
fueled by fires of doubt and fear,
no one lets the other near.

Open eyes to perfect love,
gift of wonder from above.
A love that gives, never takes,
love that grants others mistakes,
that counts no loss and no gain,
that makes our hearts young again.

Copyright 2012, John Paul Mueller

 

Central Clearing House for Book Contacts

A reader wrote to me the other day with an idea for creating a central place where any reader could contact any author with book-related questions. It would be a social media type idea along the lines of Facebook, Twitter, or LinkedIn, but with a book focus. The way this idea works is that a reader could leave a question on the central site and then the author would receive a notification through e-mail about the question. The question and its answer would remain public. That way, other readers with the same question would see the answer and not have to ask the author about it again.

This blog fulfills the idea that the reader has to a certain extent. When I receive e-mails from readers, I determine whether the question has enough interest to affect a large number of readers. When the question is better answered publicly, I put an answer up here, rather than answer it privately. Of course, there are times when a reader question needs and deserves a private answer. Using the blog approach does make it easier for me to handle some questions discretely, but nothing would keep me from including an e-mail address for that purpose in the book. The problem with this blog is that reader need to know to look here for answers. Even though I publish the URL for this blog in all of my books, readers still managed to miss it somehow and I get queries in e-mail about the availability of such a central knowledge store.

Wrox provides a centralized location for readers to exchange information of the sort that the reader mentioned, but it’s not as well known as the social media sites and I didn’t think to include the URL for it in my book (the publisher does include it as part of the Introduction). My experiences with Professional IronPython, Professional Windows 7 Development Guide, and C# Design and Development tell me that the concept is good, but reader participating is often poor. I actually get a lot more input on my blog.

I like the idea this reader has because it provides a social media type approach to a pressing need authors have to service reader requests for information. The problems are figuring out how to present the idea publicly, implement the idea in software, and then to make the site popular enough that it actually does what it’s supposed to do.

Of course, I’m always looking for input from you on making things work in a way that’s easy for you. What do you think about this concept? Is it possible to create such a site and have it become a success? Would you even frequent such a site? Let me know your thoughts on the matter at John@JohnMuellerBooks.com.

 

The Art of Observation and Writing

People watching is a favorite activity of mine. No, I don’t sit at the bench at the mall and make snide remarks about people’s attire. I’m also not too interested in the exceptions to the rule—someone doing something so absurd that it falls well outside the range of normal human activity. (Although, I must admit that the guy who ended up in a fountain because he wasn’t looking as he was texting, was sort of funny.) No, I’m more interested in how normal people react in normal ways to normal situations. Observation is a key tool for any author because seeing how people act and react is an essential part of communicating thoughts and ideas to them. I can’t see my reader during the reading of one of my books, so observation helps inform me outside of that environment.

On one particular day, I was watching a young couple argue. The precise reason for the argument isn’t known to me and it’s immaterial anyway. The two of them argued for quite some time, each insisting the other wasn’t listening. Both went off in a huff. I’ve always hoped that they made up. The things that struck me was that the two people communicated differently. The wife’s communication was both vocal and emotional. However, it was her body language that said the most. The husband was stiff as a board and you could tell that he had built defenses against any encroaching information that might conflict with his preconceived ideas of how the communication should go. However, he did use his hands quite a lot and did make really good eye contact. His choice of words was the key ingredient in his communication. Two people, communicating two completely different ways, and neither of them hearing the other.

Books are like that sometimes. I get e-mail from my readers that makes it obvious that I didn’t choose the correct manner of communication. Yes, the information they’re requesting is most definitely in the book, but they didn’t see it because the information didn’t appear in a form that attracted attention. In some cases, the reader did see the information, but couldn’t understand it. In a worst case scenario, the reader saw the information, read it, thought it was understandable, and then didn’t apply it correctly. In many cases, I find that the reader really didn’t understand the information after all.

Another couple, on another day, showed me something else. Nuance is often part of communication. The precise formulation of interaction is important. In this case, the husband was following his wife shopping, but I could tell that his interest lay in his wife, not in what she was buying. She picked a particular item up, looked it over, and put it on the shelf. A little while later, they came back. She picked up the same item, looked at it intently, and then put it back on the self. I was surprised to see the man come back sometime later. He bought the item and almost passed me by while wearing a magnificent grin. When asked what was up, he explained that by observing his wife, he found the perfect gift for her—something she really wanted, but didn’t buy because it was too expensive.

The communication between author and reader is often nuanced in ways that defy simple explanations. Yet, when they’re understood, they seem absurdly simple. It’s the reason I employ beta readers, ask questions on this blog, and maintain statistics for my books. All of these observation techniques tell me how you’d like to receive information from me without my having to ask the question directly. I can provide you with the perfect presentation without saying anything at all.

How do you employ the art of observation? Do you find that it provides an effective means of communicating thoughts that might not receive proper treatment when spoken. Send your ideas on the topic to John@JohnMuellerBooks.com.