|
Sponsored Links
Resources
Enterprise Java
Research Library
Get Java white papers, product information, case studies and webcasts
|
News
News
News
|
Messages: 2
Messages: 2
Messages: 2
Printer friendly
Printer friendly
Printer friendly
Post reply
Post reply
Post reply
XML
XML
XML
|
 |
Moron – I mean, more on - writing news posts
In "Tips on Writing News Posts, Reviews, Cartoons for TSS," I addressed the format of writing reviews and news posts for TSS. I skipped articles, but that's a separate thread (i.e., for the future.) I'd like to make this the White page to the previous Red, if I can allude to history, by addressing not the physical form, but the intent of writing for TSS.
"How to write" is, and always will be, a challenge, especially for technical people like us. We tend to write because we have to, not because we want to. We work well within syntactic constraints – give us a BNF, or something generated from a BNF, and we're happy.
There are rules in writing, too, though, and since we're rules-oriented, that helps. I'd like to look at another aspect of writing – the rules – so that everyone benefits. As usual, I'm not the be-all and end-all of human communication, so feel free to weigh in.
The first rule in writing is: write. It's not to get your grammer perfectly, or spellling everything right. If you've got something to say, well... saying it is better than not saying it at all. The mechanics of the message can be fixed.
After that, it's all down to writing effectively, making sure that what you want to say is actually being said, and understood. Rules apply here, too, and sometimes they're not obvious until you think about them.
Rule number two: remember the details of what you're writing, and communicate them to your readers. Probably the number one mistake of technical writing is the assumption of familiarity on the part of the reader.
That means that if you're writing about, oh, Hibernate, it's very natural for you to assume your readers know all about Hibernate, except for the parts you're writing about. Even then, writers tend to think that readers understand completely on the first reading, so they give a valid explanation that isn't clear, and then presume that explanation was understood.
No matter how much we wish we could read your mind and acquire your knowledge through osmosis, it's not going to happen.
So assume your readers are smart and that they can think, but that they're complete strangers to what you're writing about. Throw us a bone, in case we're living under a rock and don't know what Hibernate is. Maybe give us a little explanation, once we understand that Hibernate is an O/R mapper, of why what you have to say is relevant – don't assume we understand immediately. Maybe we've never dealt with caching the way you have; maybe we've never seen or thought of the problem.
This is why very little technical writing reaches the audience it should.
Rule number three: readers don't want to read this. I said this in the first article on the subject, but it's worth repeating. Readers don't want to read. They want to know.
Here's the harsh truth: you get one sentence to capture a reader. One. Not three; not two. If your first sentence is a throwaway sentence - “Have you got a bald spot?” - your news post is thrown away, too. This isn't just your readers, this is your Humble Editor, too.
I have to read a lot, and I don't need the burden of having to dig through lots of mush in order to find content. I'm probably more sensitive to this than the other readers are, but at the same time, I'm used to trying to find meat under a pile of grease; most readers typically aren't. If you can't get your message across quickly, that's an extra burden on me to dig out what you meant, to try to see the relevance.
The constant "Your Humble Editor" crap isn't actually crap – I don't consider myself to be smarter or better than my readership is. I'm just blessed to be where I am. If I have to dig out your message for you, chances are good that I will get it wrong.
You don't want that.
So make your sentences count. Tell me something; make it quick; make it understandable. If that first sentence is able to grab a reader, if it's able to communicate why a reader should be interested in reading, you've done a good job. The rest is just backing that first sentence up.
TSS is not, despite what some people say, about flamewars or hit counts. We benefit from those things, I suppose, and there's nothing like a flamewar to drive up hit after hit ad nauseum, for people looking for jabs and insults.
That said, I hate flamewars and trolling for hits is distasteful. I know TSS gets accused of it fairly often, and historically, flamewars were quite normal – but I would like to point out that I've tried very hard, and as subtly as I could, to discourage flamewars in favor of actual content.
Controversy shows up, too, but not for controversy's sake, when I can help it.
Rule number four, then, is "Make your contribution count for something." If you're writing for today, use your blog. If you're writing to improve the community, use TSS.
Again, TSS is your site. I'm not driving it; I'm also not trying to be a "star" or anything like that. There are plenty of sites out there trying to feed egos. My hope is that my readership is able to see past that, and can appreciate art for expression, not as market campaigns. (Hopefully, it will capture your imaginations.)
Thanks for reading, and I'd love to know what you think about these rules.
|
|
|
Message #239664
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: defining "flame"
Joe,
I have yet to read a post that is without merit, so-called pundits that are part of the TSS readership claim 'flame' when challenged, but in reality this is the best forum to vet out all viewpoints, and I personally hate rules of engagement, because they are based on conventional wisdom...for example, I have been called out on promotion of Glassfish at the expense of WebLogic, and questioning vendor politics on spec's, among other things...
with respect to what is "flame-bait", i see this as a mute discussion, this is just an excuse for not talking about real issues that impact the marketplace, its just that some people don't like to have anything but the prescribed banter on the board, rather than a discussion that reaches below the surface...I don't accuse you of this, at least I have not in quite some time, I think you do a good job of moderating...
but, if there are too many parameters, then TSS will succumb to staleness, and we might as well just point to press releases...let the thoughts flow freely, and the best will ultimately rise to the top; with all that said, I think the 'rules' you have enlisted are reasonable, i am just reaching out to those who hide behind the made-up word: flame....
douglas dooley
|
|
|
Message #239686
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Rules vs Reason
I think the tips address well-known problems in general technical writing on the web and perhaps even more so on TSS. There might be one fault though with the posting - the choice of words.
As much as techies hate to write and tend to assume that their readers have a certain knowledge, they also, especially when they consider themselves to have something important to say (which perhaps should be a pre-requisite for writing in the first place), they hate to have someone giving them rules on what to say and how to say it.
Again, I think Joesph's advice are to-the-point, effective and, actually, quite humble :). I would just like to remove the wording "rules" from it and focus on "tips" or "advice".
This might also be the reason for Douglas post (pardon me if I'm wrong), which, as I understand it, addresses the mis-use of the word "flame" in the context of trying to quench a healthy debate.
Here, I would like to add two general tips (a.k.a. advice. != rules), both related to "Respect your readers":
* When trying to get your message through, try to choose your words and/or tone in order for you not to sound like a preacher or a salesman. Try to be up-front with the abilities AND liabilities of what you are proposing as a solution/product/way of doing things. For one thing, your readers will be as smart, or probably smarter than you, and they will find the liabilities sooner or later and especially if you try to hide them, they will see it as a challenge to prove you wrong.
* When responding to a post which you found misleading, unintelligent, or outright offensive, resist the urge to express your instinctual feelings in colorful words. A wise person said to me: "Never write anything in anger". Instead, use questions, mild manners and a humble tone, and I guarantee that you will get your message across a lot quicker, with less effort, and with less amount of people you cannot look in the eye on the next conference. Also, you will most likely be held in much higher regard by your peers, which is probably one of the main reasons you are writing in the first place. Or in simple words, don't "flame". :)
|
|
|
| New content on TheServerSide.comNew content on TheServerSide.comNew content on TheServerSide.com |
|
|
Reza Rahman explores the features of the proposed JSR 299, Contexts and Dependency Injection for Java EE (CDI). When approved, it promises to be a key feature of Java EE 6.
(November 2, Article)
SAML is an XML-based standard for exchanging authentication and authorization data between security domains. The single most important problem that SAML was created to solve is the Web browser Single Sign-On problem. Many organizations are debating whether to stay with version 1.1 or move to 2.0. This article makes observations about both options.
(September 28, Article)
Joe Ottinger takes a look at how people learn, and applies it to the practice of programming. He notes that understanding how people learn is an essential part of working in a programming team.
(September 22, Article)
Stephen Maryka gave us an article about the Asynchronous Web and posed a number of questions that get examined like an approach to delivering Asynchronous Web capabilities through extensions to existing Java EE technologies.
(July 14, Article)
JavaServer Faces Flex goal is to provide users capability in creating standard Flex components, part of flexSDK which is open sourced through MPL license, as normal JSF components. This article by Ji Hoon Kim will provide an overview of creating a simple multilingual JSF page consisting of JSF Flex tags.
(June 29, Article)
In this session Jeff explores the key characteristics of successful SOA projects. He covers some of the patterns, and anti-patterns, tool sets, and strategies that he himself learned the hard way. Last, he provides a strategy and blueprint for achieving a high likelihood of success in your SOA project.
(June 23, Tech Talk)
Ari Zilka, CTO of Terracotta, Inc., talks about the new features in Terracotta 3.1, announced during JavaOne and available now.
(June 15, Tech Talk)
In this Tech Talk, Josh Long explores an integration challenge using Spring Integration and walks through the implementation, employing and expanding on the basic patterns of Enterprise Application Integration to tie together components into a function integration solution, and then demonstrates how Spring Integration helps address the integration requirements.
(June 15, Tech Talk)
In this Tech Talk, David Geary teaches you: The basics of Google Web Toolkit; How to implement Ajax-enabled applications in Java; Internationalization; Hooking into the browser history mechanism; Remote procedure calls.
(June 4, Tech Talk)
Jon Kern discusses the best architecture/technical solutions and ensure that they are repeated by all developers. By tackling the architecture up-front in a serial manner, subsequent parallel development will be much more manageable and predictable.
(May 28, Tech Talk)
This keynote describes the frustrations of modern knowledge workers in their quest to actually get some work done, and solutions for how to guard yourself against all those distractions. Neal Ford talks about environments, coding, acceleration, automation, and avoiding repetition as ways to defeat the misguided attempts to sap your ability to produce good work.
(May 26, Tech Talk)
Gil demonstrates how new, aggressive uses of already abundant compute capacity by common applications offer competitive value for application designers.
(May 21, Tech Talk)
Chris Keene introduces WaveMaker as a new way to automate the ability to generate Hibernate classes in order to more quickly bring OR mapping into an application.
(May 19, Article)
In this session Nati Shalom demonstrates how to take a standard Java EE web application and scale it out or down dynamically without changes to the application code. Seeing as most web applications are over-provisioned to meet infrequent peak loads, this is a dramatic change because it enables growing your application as needed, when needed, without paying for unutilized resources.
(May 19, Tech Talk)
Mastering EJB was one of the original and most influential EJB books in the industry. Mastering EJB III now returns with two new expert co-authors, updated for EJB 2.1 and 30% new chapters including security, integration, best practices, open source, and more.
(Book PDF Download)
The Application Server Matrix is a detailed listing of J2EE vendors and their application server products, with information on latest version numbers, J2EE spec support and licensing, pricing, platform support, and links to product downloads and reviews.
(Application Server Comparison Matrix)
|
|
