A Technical Writer Writes (Comments)https://blogs.oracle.com/techscribe/feed/comments/atom2010-02-10T17:23:26+00:00Apache Rollerhttps://blogs.oracle.com/techscribe/entry/blah_blah_blarticle#comment-1211313285000Re: New Words for the New Millenniumintechs.com2008-05-20T19:54:45+00:002008-05-20T19:54:45+00:00
<p>Old blog but interesting discussion of the new and the old Technical Writer. How would we be classified?</p>
https://blogs.oracle.com/techscribe/entry/time_to_go_home#comment-1202431278000Re: Time to Go HomeMike Unwalla2008-02-08T00:41:18+00:002008-02-08T00:41:18+00:00
<p>Paul, technical writers perform a valuable function, and I too am dismayed when I come across the 'anyone can write' argument. However, your colleague makes a valid point about grade C documentation being good enough. Documentation is a means to an end, not an end in itself. Documentation exists to make money (or reduce costs) for your company. (It does that through helping customers to use products.)</p>
<p>Quality is the &quot;degree to which a set of inherent characteristics fulfils requirements&quot; (ISO 9000:2005). If grade C is good enough, that is, it fulfils requirements, producing grade A documentation would be wasteful of resources.</p>
<p>The principle of 'good enough' applies to all products and services on the market. Most purchasers cannot afford the best (grade A), even if they desire it. Why should that be different for documentation? The cars we drive, the houses we live in, the clothes we wear. All could be better, but we get by with 'good enough'.</p>
https://blogs.oracle.com/techscribe/entry/time_to_go_home#comment-1194549260000Re: Time to Go HomeJaniceG2007-11-08T19:14:20+00:002007-11-08T19:14:20+00:00
<p>Having just had to essentially rewrite an entire installation guide because the product could not get a writer assigned to them due to the area's VP deciding that his writers should be spending their time on blogs, wikis, and other wonders of the electronic age, this entry really hit home. The guide was written by one of the product's engineers for whom English is not his native language and who had never written documentation before. He also insisted that the document remain in StarOffice so the engineers could &quot;own&quot; the source and update it. </p>
<p>Eduardo, much as it pains me to admit it, a traditional edit is not going to adequately be able to fix a document with poor or no structure and awkward English in nearly every other sentence. For a short article or the like the problem might not be so bad, but for actual product documentation that is intended to be an overall guide to the product and how to use it, there's only so much that an inexperienced engineer can be expected to do. And only so much that an editor can do to fix it without practically starting over from scratch.</p>
<p>Obviously, I agree with Steve, Jeff, and Paul. Programmers would not expect an administrative assistant to be able to write acceptable, useful code, and it's a continuing source of annoyance to me that engineers and management cheerfully assume that programmers can write acceptable, useful documentation as well as technical writers can.</p>
https://blogs.oracle.com/techscribe/entry/time_to_go_home#comment-1193382260000Re: Time to Go HomeJeff Gardiner2007-10-26T07:04:20+00:002007-10-26T07:04:20+00:00
<p>Paul,<br/>
I applaud you for making a statement like this. You've raised the Q-word, a word that has seemingly become inappropriate in polite or strategic conversation. The reasons for that are many, but the obvious one related to your topic is that once you invite submissions from engineers, some of whom will be writing in English as a second language, you have to accept a lowering of quality. I could, but won't, offer a number of examples from texts that the editors have worked on. And before anyone thinks we are raising a subjective standard of taste, i.e. sentence A by TW is more elegant than sentence B by ENG-ESL, let me state that we aren't. We are talking about readability and translatability. Poorly written sentences are a barrier to understanding and use of our products, and they are expensive. The obvious expense is in translating costs (25 cents per word x 9-14 languages--and that figure might have risen to 35 cents). The less obvious expense, because good editing is invisible, comes from the increase in editing time required to deal with ESL documents. On the average, IPG editors spend approximately 3 times as much time editing an ESL engineering document as they do editing a document from one of our technical writers. At a time when the editors have about an 18-to-1 writer-to-editor ratio, the addition of texts to be edited from engineers, especially those with ESL, places an extraordinary burden on their time. That is time taken away from style issues, including the new ones emerging along with our new content types (like the text in screencasts), and the involved writer-editor exchanges with our TWs that help produce quality documents.</p>
<p>All that said, I do not share your pessimism, but I do share your concerns. One reason why I don't share your pessimism is because you have the courage to raise this issue and others in your blog. You are not alone in these concerns; there are many other writers in this department who feel the same way. Hopefully your blog provides a forum for their voices in our ongoing departmental discussions.</p>
https://blogs.oracle.com/techscribe/entry/time_to_go_home#comment-1193309394000Re: Time to Go HomePaul Davies2007-10-25T10:49:54+00:002007-10-25T10:49:54+00:00
<p>Steve, I fully agree with your observations about the efficiencies of specialization. One of my most important skills as a technical writer is to be able to view technology through users' eyes while working in the environment where the technology is developed. I have developed this skill only through the continual practice that comes through specializing in technical documentation. I have noticed that even engineers with good writing skills have a tendency to focus more on the internal implementation than on the users' point of view. Given that it's the job of engineers to implement the technology, such a tendency is natural and completely appropriate.</p>
<p>Eduardo, thanks for the endorsement! I agree that different forms of technical writing require different approaches, although some general principles, such as the inverted pyramid style, apply to all factual writing. The partnership between writers and engineers to which you allude in your second thought has always been a feature of the documentation projects that I have worked on. However, for the reasons that I suggested in my response to Steve, some forms of technical writing, notably task-focused information, benefit from a greater level of involvement from the technical writer than subedting content that an engineer has written. The role of writer as subeditor is most suitable for technical descriptions in the form of articles, design specifications, technical papers and, of course, blog postings.</p>
https://blogs.oracle.com/techscribe/entry/time_to_go_home#comment-1193120623000Re: Time to Go HomeEduardo Pelegri-Llopart2007-10-23T06:23:43+00:002007-10-23T06:23:43+00:00
<p>Hi Paul. I certainly appreciate how hard it is to write well and the value that technical writers can contribute to the software industry. Here are two thoughts prompted by your writeup...</p>
<p>A novel is very different from a Newspaper article; these two modalities address different needs in the readers, are written within different constraints and exploit different skills in their authors. I think the same variation should exist in technical writing: good writing will continue to be extremely important, it just needs to be adjusted to each of the modalities, from blogs to printed books.</p>
<p>The second thought is on the value of editor. It seems to me that the combination of engineer-contributed content with strong editorial action might be very effective in generating useful and timely documentation.</p>
<p> - eduard/o</p>
https://blogs.oracle.com/techscribe/entry/time_to_go_home#comment-1193093352000Re: Time to Go HomeSteve Cogorno2007-10-22T22:49:12+00:002007-10-22T22:49:12+00:00
<p>Paul,</p>
<p>This is a sad commentary on our industry, but unfortunately, I fewer people see documentation the way you and I do.</p>
<p>Let's set aside the quality issues related to engineer-created documentation for a second. (Surely there are some engineers -- me excluded -- that can write decent documentation.)</p>
<p>Basic economics dictates that documentation created by someone dedicated to technical writing is economically more rational. Specialization is the hallmark of efficient markets. A country, person, whatever is more efficient at producing widget A. Some other entity is better at producing widget B. The most economically advantagous situation is for entity A to make only widget A, entity B to make only widget B and the two entities to trade.</p>
<p>Specialization is efficient. Physicians specialize into narrow fields because it isn't economical for them to be generalists. Likewise, it isn't efficient for engineers to divide their attention between developing software and documenting it. We should encourage people to focus their energy around what they do best.</p>
https://blogs.oracle.com/techscribe/entry/where_s_the_faq#comment-1191929593000Re: Where's the FAQ?Dixie Pine2007-10-09T11:33:13+00:002007-10-09T11:33:13+00:00
<p>With the volume of reading on my plate, I am happy to find FAQs that will give me a quick clue about whatever new thing I have to learn. That said, if these FAQs do not include links to in-depth, trustworthy documentation, I am annoyed because now I have to go hunting for yet another means (a blog? a podcast? a manual? a forum?) of expanding my knowledge on the thing I need to learn about. FAQs with useful links are my friends. Trumped up questions with no links are just clutter.</p>
https://blogs.oracle.com/techscribe/entry/where_s_the_faq#comment-1191861135000Re: Where's the FAQ?Walter Bays2007-10-08T16:32:15+00:002007-10-08T16:32:15+00:00
<p>Well of course it's because we're all so lazy. Show me a 100 page manual and I'll look for the 2 page FAQ to get started, hoping the other 98 pages were repetitive and unnecessary filler. Let present trends continue a few more years and we'll have 100 page FAQ's, at which time readers will look for the 2 page overview instead. By the way, I've watched PM question time, and he gets nothing like the &quot;softball&quot; questions typical of FAQ's.</p>
https://blogs.oracle.com/techscribe/entry/jakob_nielsen_comes_to_the#comment-1191595175000Re: Jakob Nielsen Comes to the Sun Microsystems Editorial ForumJeff Gardiner2007-10-05T14:39:35+00:002007-10-05T14:39:35+00:00
<p>Paul,<br/>
You've done a superb job capturing and discussing the issues raised by Jakob.</p>
<p>I have a few points to add. After his talk, Jakob said to me that he couldn't urge us strongly enough to do usability testing of our new approaches. As a department, we haven't done many usability studies since Marney Beard and her usability testing group moved out of mpk17 years ago. Whether or not we have the time and resources to conduct tests, his point was a good one. We are moving into new forms of communication with our users and collaborators based on our sense of trends and the preferences of key internal stakeholders. Both legitimate motives for doing this, but neither gives us much to evaluate. </p>
<p>It would be useful and interesting, I believe, to see, for instance, how successfully a user finds technical information on a blog...finding user information in a current blog posting and then finding information in a posting dated months ago. </p>
<p>Or setting up a test to determine the effectiveness of putting out information on facebook. Dave Lindt brought up good points during the talk about whether teenage users of those sites might expect a different kind of writing style. Do we know what that style is? Maybe if we hire teenage interns, we will.</p>
<p>Will we even know and be able to respond quickly enough to changes in the demographics of sites like facebook?</p>
<p>On the matter of publishing information or advertising Netbeans Beer Bashes on facebook, there is a very interesting study of facebook by the Fabernovel Consulting firm at <a href="http://www.slideshare.net/popular" rel="nofollow">http://www.slideshare.net/popular</a></p>
<p>There are a few points there that should be taken as cautionary. One, the demographics of these sites change rapidly; I would say probably more rapidly than we are likely to keep up with unless we have resources dedicated to researching trends, countertrends, and disappearing trends. </p>
<p>This study shows that the demographics of facebook just in the last year have shifted from over 50% of its membership being in the 12 to 24 age range to over 50% in the 25 and older range, with the over 35 set being now the largest demographic segment. If we apply retro-causality, we might catch our intended youth movement developers of the future. If we don't, we'll be talking to ourselves by the time we get info out to facebook.</p>
<p>Two, another important point that they make is that &quot;designing and spreading an application on Facebook requires a particular expertise that media companies seem to lack&quot; and &quot;Their applications fail to draw massive amount [sic] of daily active users.&quot; But before you object and claim &quot;but IPG isn't stuffy like CBS News or the New York Times,&quot; their next point is &quot;Even Yahoo!, a company that knows how to distribute media on the Web, had to turn to application giant RockYou to redesign its application and attract users.&quot;</p>
<p>There is more there on slide 22. All worth emblazoning on our collective strategic brains before we make the same mistakes we used to make when word processing became a wysiwyg thang, i.e. too many writers then thought that they were the re-incarnation of William Blake or Dante Gabriel Rossetti and could both write and do visual design. Or, at least, they thought they could match Jan Tscichold on the typographic design front. Thank god for the Mike Quillmans and Mike Patinos of our world and their visual skill and expertise. </p>
<p>That's a Friday afternoon digression...but then I have plenty of time due to no facebook action. Maybe that's because I was invited to join facebook by my daughter (I told her that my interest was strictly sociological and that I still loved her mother), bless her, or maybe it's because I haven't posted a picture of me or my psychotic dog, or maybe it's because I am a few standard deviations beyond the age of the dating demographic, or maybe it's because I didn't post any java code samples there...</p>
https://blogs.oracle.com/techscribe/entry/jakob_nielsen_comes_to_the#comment-1190789470000Re: Jakob Nielsen Comes to the Sun Microsystems Editorial ForumJim Siwila2007-09-26T06:51:10+00:002007-09-26T06:51:10+00:00
<p>Thanks for this extensive recap, Paul. I wasn't able to attend Jakob's presentation, so this is great for me.</p>
<p>To deal with the issues of aging information and unauthenticated information (especially for B2B), we are going to have to establish a hierarchy or flow to help readers get from blogs to relevant docs, wikis, articles, etc. We've done that with release note, What's New, and docs. People understand the flow through those documents, and we have ingrain a similar understanding with these new sources. For awhile anyway, it is going to have to be explicit. Perhaps some of this can be handled with simple boilerplate references to key info sources and indications of the editorial control exercised over each of those sources. </p>
<p>To meet the need for brief, focused information, we need to tag all our information finely enough to be found. Blogs aren't the only things that are brief. Sun documentation has an abundance of highly focused information in brief chunks, but it often isn't possible to pull them out of the books they are contained in.</p>
https://blogs.oracle.com/techscribe/entry/jakob_nielsen_comes_to_the#comment-1190758595000Re: Jakob Nielsen Comes to the Sun Microsystems Editorial ForumJaniceG2007-09-25T22:16:35+00:002007-09-25T22:16:35+00:00
<p>Thanks for this extensive review.</p>
<p>\*\*\* Geertjan Wielenga suggested that the problem of retrieving old information from a blog archive could be addressed through providing a table of contents for the topics in the blog. The blog as book, if you will. \*\*\*\*</p>
<p>That solution only covers the topic titles, not the content. If a blogger uses titles like &quot;Cool New Feature!!!&quot; or &quot;Useful Script&quot; then a ToC is useless. Plus, if a blogger is making daily (or even more frequent) entries, then the ToC would soon be unwieldy. Grouping listings by month or date would mean that readers would have to remember not only the topic title but approximately when it was posted. Not sure this works as an answer to enabling readers to find information. I could easily envision a scenario where a user remembers seeing an entry at some point with useful information but didn't take careful note of it because it wasn't relevant at the time they read it.</p>
<p>I was able to ask Jakob my question in the meeting, regarding whether the use of both blog postings and more persistent user information to provide documentation about a product meant that we were forcing users to look in two places and what should be done about integrating the information. His response was that the blog entry could provide a pointer to the persistent documentation. </p>
<p>Although I didn't pursue a follow-up in the meeting, I would have liked to have pointed out that this solution works in the direction blog-&gt;user doc but not in the opposite and more problematic direction, user doc-&gt;blog when blog entries document something that the persistent documentation doesn't cover. If blog entries are ephemeral and difficult to search but are covering aspects of a product that would be useful to users who don't necessarily access blogs, then this is a problem that needs to be solved.</p>
https://blogs.oracle.com/techscribe/entry/blah_blah_blarticle#comment-1190683117000Re: New Words for the New MillenniumJaniceG2007-09-25T01:18:37+00:002007-09-25T01:18:37+00:00
<p>For clarity, might want to add the word &quot;impulsively&quot; to the definition of &quot;blemoan&quot; (&quot;To regret impulsively posting a blarticle&quot;)</p>
<p>\*\*\* I realized that &quot;blart&quot; needs a counterpoint to denote the thoughtful, considered posting of a blarticle - &quot;blarticulate&quot; perhaps \*\*\*</p>
<p>Not sure about this one... I know that I, for example, can be both articulate and impulsive at the same time :-&gt; (Reaching here... &quot;blassemble&quot;?)</p>
https://blogs.oracle.com/techscribe/entry/blah_blah_blarticle#comment-1190365092000Re: New Words for the New MillenniumPaul Davies2007-09-21T08:58:12+00:002007-09-21T08:58:12+00:00
<p>JaniceG, you wouldn't be an editor by any chance, would you?</p>
<p>From your proposed change to the definition of &quot;blarticle&quot;, I realized that &quot;blart&quot; needs a counterpoint to denote the thoughtful, considered posting of a blarticle - &quot;blarticulate&quot; perhaps? And yes, we should also have &quot;blemoan&quot;.</p>
<p>To the person who commented anonymously: I was actually the one who started the kicking and screaming (so to speak) with my initial response to the suggestion to put ourselves on YouTube. </p>
<p>My experience of Sun's editorial style guide as both user and contributor is that it advocates less a &quot;depersonalized&quot; style than a second-person style. From a chat I had with a member of Sun's media arts group, I got the impression that this style is very well suited to one of the new information types that Sun's technical writers are being encouraged to produce, namely screencasts.</p>
<p>Sue, as more and more documentation is supplied as blikis, I suspect that the tech writers of the new millennium will be &quot;customers&quot; or maybe, in the world of free open-source software, &quot;users&quot;.</p>
https://blogs.oracle.com/techscribe/entry/blah_blah_blarticle#comment-1190322668000Re: New Words for the New MillenniumSue Weber2007-09-20T21:11:08+00:002007-09-20T21:11:08+00:00
<p>And are tech writers of the new millenium &quot;blartists&quot;?</p>
https://blogs.oracle.com/techscribe/entry/blah_blah_blarticle#comment-1190316705000Re: New Words for the New Millenniumguest2007-09-20T19:31:45+00:002007-09-20T19:31:45+00:00
<p>I bet there are just as many tech writers running along side of you as there are kickers and screamers. As far as I know there are gratefully no kickers or screamers in my neck of the woods. But thanks for the new term. I am trying to become a blarter but it is hard as I have spent the last 10 years mastering the depersonalized style that our editorial guidelines tell us to use.</p>
https://blogs.oracle.com/techscribe/entry/blah_blah_blarticle#comment-1190316228000Re: New Words for the New MillenniumJaniceG2007-09-20T19:23:48+00:002007-09-20T19:23:48+00:00
<p>Given the definition of &quot;blart,&quot; you might want to add an adverb to &quot;blarticle&quot;: &quot;Bite-sized chunk of information, usually written in a personal style, often impulsively&quot;</p>
<p>And as a corollary, should we also have &quot;blemoan - To regret posting a blarticle&quot;? :-&gt;</p>
https://blogs.oracle.com/techscribe/entry/review_request_application_server_9#comment-1189101381000Re: Review Request: Application Server 9.1 DocumentationPaul Davies2007-09-06T17:56:21+00:002007-09-06T17:56:21+00:00
<p>Thorlief, Thank you for your comments and for your feedback on the Performance Tuning Guide. I hope to address your feedback in the coming week or so.</p>
<p>The GlassFish wiki is a community site, while wikis.sun.com is a Sun-branded site. It would not be appropriate to host a community project on a Sun-branded site. </p>
https://blogs.oracle.com/techscribe/entry/review_request_application_server_9#comment-1188622998000Re: Review Request: Application Server 9.1 DocumentationThorleif Wiik2007-09-01T05:03:18+00:002007-09-01T05:03:18+00:00
<p>By the way, did you considered to move glassfish wiki contentent to <a href="http://wikis.sun.com" rel="nofollow">http://wikis.sun.com</a> , the confluence software is much easier to use than jspwiki, which is used for <a href="http://wiki.glassfish.java.net/" rel="nofollow">http://wiki.glassfish.java.net/</a> .</p>
https://blogs.oracle.com/techscribe/entry/review_request_application_server_9#comment-1188622842000Re: Review Request: Application Server 9.1 DocumentationThorleif Wiik2007-09-01T05:00:42+00:002007-09-01T05:00:42+00:00
<p>I already added some parts in June,<br/>
but the GF PerformanceTuningGuide<br/>
ist still refering to Solaris 8 defaults on Page95 , not Solaris 10....<br/>
<a href="http://wiki.glassfish.java.net/Wiki.jsp?page=PerformanceTuningGuide" rel="nofollow">http://wiki.glassfish.java.net/Wiki.jsp?page=PerformanceTuningGuide</a></p>
https://blogs.oracle.com/techscribe/entry/virtual_steve_comes_to_the#comment-1185372803000Re: Virtual Steve Comes to the Sun Microsystems Editorial Forumalan mcclellan2007-07-25T14:13:23+00:002007-07-25T14:13:23+00:00That comment about the "replacing the motherboard" topic on the Info Central blog is certainly valid. In our case, putting that info in the blog was kind of a stop-gap way to get info out (in an afternoon) without formalizing it in an article or document. As a small team trying to cover a lot of territory, we thought that an acceptable solution, especially since blog entries are searchable on the Info Central site. My personal preference would have been to put this particular item in an online bulletin board, which is yet another type of community. https://blogs.oracle.com/techscribe/entry/virtual_steve_comes_to_the#comment-1185022050000Re: Virtual Steve Comes to the Sun Microsystems Editorial ForumChris Kutler2007-07-21T12:47:30+00:002007-07-21T12:47:30+00:00Oops, a typo. I meant to say "we do not think that all our tutorials should be posted to our blog." (not YOUR blog).https://blogs.oracle.com/techscribe/entry/virtual_steve_comes_to_the#comment-1185021509000Re: Virtual Steve Comes to the Sun Microsystems Editorial ForumChris Kutler2007-07-21T12:38:29+00:002007-07-21T12:38:29+00:00<p>Just to clarify. We (the tutorial divas) do not actually put actual tutorial drafts out. We put out material that we might turn into a tutorial. When we see some entries become widely accessed, we use that information to help us prioritize the tutorials we plan to write, or choose to include similar tutorial in a related tutorial.</p>
<p>When we post how-to information we keep it short and simple. We will post complex information if we see a need to get that information out fast, but then follow up with getting that information into a traditional document. If we were to turn the info into a full blown tutorial we will add a link to the blog entry, but we would never delete it as people do return to our entries over and over. If the information is obsolete, we try to update the entry with a note to that fact and point to more current information if possible.</p>
<p>I think I speak for both of us when I say that we do not think that all our tutorials should be posted to your blog. A well organized portal is a much better place for traditional docs, and traditional docs still play an important role in product adoption. The purpose of our
blog is to connect with our readers on a more personal level, and to enhance the traditional deliverables, not replace them.</p>
<p>Enhancing usability to decrease the need for documentation should always be our goal. However, we can also minimize the traditional deliverables by eliminating redundant or unread/unnecessary documentation. Not only does this give us more time to focus on meeting our customers' needs through different, but more appropriate media, but it makes it easier for our customers to find the information by eliminating detritus that they have to weed through to find the gems.</p>https://blogs.oracle.com/techscribe/entry/virtual_steve_comes_to_the#comment-1184969126000Re: Virtual Steve Comes to the Sun Microsystems Editorial ForumRichard Friedman2007-07-20T22:05:26+00:002007-07-20T22:05:26+00:00Thanks for distilling this discussion, which I wasn't able to make in person.
Judging from my own use of blogs in areas outside of computers (music, photography, literature, art, politics), blogs are useful to find out what's going on, what people are doing, and what's newly cool. And, they point you to other places on the web that I might or might not find interesting. E.g. I like the content on person A's blog, and from their blogroll I can tell that they are reading person B (and C, and D, and ...), so maybe I should take a look at what those folks are saying too. (This cascades quickly into an avalanche, but if you apply restraint you can find some valuable information.)
But I don't expect to find IN DEPTH information here. My hope is that if someone is saying "Look what I did with this new XYZ thingo", they will also include a link for more information about that thingo.
In most cases I would never have known that this thingo even existed. (It's what we don't know we don't know that is most important to know.)
So blogs "curate" information for us. If we find a channel of interest, maybe that can lead me to something I didn't know about but should know about.
So blogs, in my understanding, don't replace in depth content, only illuminate it. And it's the blogger to tell us where to go next after they raise the subject. At least, that's what the GOOD BLOGGER must do. And their blogs are a treasure.https://blogs.oracle.com/techscribe/entry/virtual_steve_comes_to_the#comment-1184968018000Re: Virtual Steve Comes to the Sun Microsystems Editorial ForumVirtual Steve2007-07-20T21:46:58+00:002007-07-20T21:46:58+00:00[Trackback] This week I dropped in on the Sun Editorial forum.&amp;nbsp; Paul Davies has a nice write-up .&amp;nbsp; It's worth reading -- and I think Paul spent more time writing about it than I spent saying it!&amp;nbsp; I've found it very interesting to have this ongoin...https://blogs.oracle.com/techscribe/entry/screencasts_and_books_there_s#comment-1183114584000Re: Screencasts and Books: There's a Place for BothSueAnn Spencer2007-06-29T10:56:24+00:002007-06-29T10:56:24+00:00Paul, I'm another writer who is glad that you extended this discussion. It is an important topic! Both screencasts and traditional information delivery mechanisms have a role. Working out what those roles are is an exciting challenge.
<p>Seems to me that blogs are good for more experienced users only. Not sure that more novice users are helped, as blog content (when done well) dips directly into an already understood topic. Traditional information delivery methods provide the systematic direction that novice users need. I do think both have a place, and thus I don't see that blogs can replace traditional docs.
<p>And I'm not convinced it's useful to make screencasts of wizards. The whole point of a wizard is to allow a user to step through first before acting, if a user wants to learn what's what.
<p>In fact, I think screencasts of any procedure are a problem, because I don't have a monitor large enough to watch the screencast AND do what it tells me to do. When I have to take notes so that I can then do the work, I'm one unhappy user. https://blogs.oracle.com/techscribe/entry/screencasts_and_books_there_s#comment-1182748895000Re: Screencasts and Books: There's a Place for BothJanice Gelb2007-06-25T05:21:35+00:002007-06-25T05:21:35+00:00<p><i>It's almost like the difference between a book and a newspaper, it's not that one is wrong, but they're for very different things.</i></p>
<p>I think this is a very important point. A newspaper is an ephemeral reporting of a point in time. A book is a long-lasting record that has been organized and whose information is easily retrievable.</p>
<p>Similarly, I think that blogs are a great immediate medium to get people excited about a product or a nifty product feature or to communicate news about a product. However, I don't think that ephemeral personal enthusiasm is a good substitute for a manual that is well organized, authoritative, and provides all relevant information in a known and searchable location.</p>https://blogs.oracle.com/techscribe/entry/screencasts_and_books_there_s#comment-1182640096000Re: Screencasts and Books: There's a Place for BothSteve Wilson2007-06-23T23:08:16+00:002007-06-23T23:08:16+00:00Paul, this is a really nice entry. Thanks for pushing forward the discussion. One more thought on the "Books vs. Blogs" comment (which I'm glad generated some controversy!).
<p>
One advantage to Blogs is the immediacy. You don't ever need to wait for the next revision of something. There is no next revision, you can just fire away as soon as you learn something new. There is obviously always going to be a place for books/manuals, but I think the NetBeans is an example of a team that does a great job using their blogs as a way to constantly bring new content to users. A few of them have used their blogs to become cornerstones of the entire community (and in fact have hugely contributed to growing that community). You might want to check out Romen's or Geertjan's blogs as examples. It's almost like the difference between a book and a newspaper, it's not that one is wrong, but they're for very different things. I just think that traditionally we've spent too much effort on manuals and can put more effort into the "newspaper" style of doing things.https://blogs.oracle.com/techscribe/entry/screencasts_and_books_there_s#comment-1182536771000Re: Screencasts and Books: There's a Place for BothPaul Davies2007-06-22T18:26:11+00:002007-06-22T18:26:11+00:00r v I know what you mean about never reading documentation except in desperation. I'm exactly the same myself, and I write the stuff for a living.https://blogs.oracle.com/techscribe/entry/screencasts_and_books_there_s#comment-1182536432000Re: Screencasts and Books: There's a Place for Bothr v2007-06-22T18:20:32+00:002007-06-22T18:20:32+00:00I seem to remember also that technical manuals are unsigned because of a lawsuit in which, following a user injury not prevented by the directions, the author got sued by the injured party. So beware, all you tech authors re-converted to bloggery.
I also agree that when I am looking for the solution to a problem (and let's face it, NO-ONE reads the manual except as a last resort), I want to get in, find it and get out. I don't want to have to page through screeds of chat, or worse, be forced to watch minutes on end of videos. There is no substitute for a properly indexed user manual, preferably available both on paper and online.