Welcome to TechWhirl Forums

Sign in or Register to get involved in our discussions.


It’s Time for a New Doctrine of Technical Communications

TechWhirl WebsiteTechWhirl Website United StatesPosts: 396 admin
edited September 2013 via Wordpress in Customer Experience Management
imageIt’s Time for a New Doctrine of Technical Communications

There is little doubt that technical communications is in crisis.Tech Comm 2.0 is what we have now, the result of a profound change in technical communications doctrine that occurred in the 80s and 90s. What we need now is a new doctrine of technical communications, a Tech Comm 3.0. The old tech comm doctrine is publication-based, but most technical communication taking place today is conversation-based. Not only does this affect the way tech comm should think about mechanical purity, it should also change the way it thinks about project scope.

Read the full story here

«1

Comments

  • Matthew HelmkeMatthew Helmke Posts: 1 ✭✭
    via Wordpress
    I think you nailed it. Well done.
  • Pamela ClarkPamela Clark Posts: 2
    via Wordpress
    +1

    One phrase in your article resonates in particular "no place in a conversation for an intermediary or an editor". Thus the rise of "communities" around technologies and products, and wikis, forums, and the rest, as we know.

    Regarding the product life cycle, I was a bit disappointed that you didn't discuss continuous publishing. As new "young" products get released and substantial new features are added to still-young software products, often more information becomes available after the product release. Yet, there is often no mechanism for addressing the information that becomes available through use of the product/software (incorporating into formal docs, archiving in knowledge base, something to make it findable for others). And, often no attempt by formal tech "pubs" departments to continue to address the information needs of the released version. I know you argue for getting out of publishing, so maybe the term "continuous publishing" needs to be revisited. But some way of continuously addressing information needs to be part of the new paradigm. I guess this is the ongoing nature of "conversation" among people with common interests - the content of the conversation continues to evolve over time. Current documentation mechanisms largely ignore released versions of their products.
  • [Deleted User][Deleted User] Posts: 0
    via Wordpress
    As usual, awesome!

    I always like writing for a blog better than a print magazine (no word count limit). Both Jack and I were really wanting to say much more than we were able to in such a small space. But, given that we're not committed to writing the book that's stuck inside our heads, we decided to tackle this and other topics one at a time.

    That said, I think it's important that folks like us continue to call it as we see it. We won't always see eye-to-eye, but challenging the status quo is something that's not only needed, but is healthy for our discipline.

    Pamela Clark is right, as well, it's critical that organizations (in order to be most effective) involve everyone in all parts of the product experience lifecycle: the customers who share feedback, the sales people who sell the product, the trainers who teach people to use it (when that's the case), the support agents that collect complaints about it -- and resolve problems that customers have with it, and the people who handle product returns (in the case of things that are returned for not working as promised). We need to incorporate the social platforms on which people interact to promote our products and to listen for additional feedback. And all of this needs to be weaved back into the content lifecycle in an effort to improve the content and the customer experience.

    I agree that publishing may not be the right word, but it will be one of the words (if not the main one) people use for quite some time. So, while I'd love to get all semantic and propose new terminology, I know those vocabulary words are buzz-worthy, but unlikely to replace the commonly understood ones. I agree, that content is provided as more of a service and is not always published or delivered - sometimes, it's just made available. So, clearly there is a better way to describe it, but I'd say that's less of an issue than getting our peers to think differently.

    To be clear, while I enjoy waxing poetic on topics such as these, there is no one approach, nor lifecycle, model, standard, etc that is right for all. But, it's also clear that there are new opportunities for us today that were not just a few short years ago. I am excited to be involved in a career that allows me to be challenged to think differently so often.

    Thanks again, Mark for the thoughtful content.
  • Sarah O'KeefeSarah O'Keefe Posts: 5
    via Wordpress
    Nice work, Mark. I think I need a template for:

    "Another brilliant article by Mark Baker: /insertlink/"

    One point I would add to your article is the importance of publishing velocity. Many tech pubs departments are not set up to publish quickly. The result is that updates take too long and "nobody reads the documentation" because it is not keeping up with the changes. The solution to this is to develop processes that close the gap between tech comm and readers -- eliminate time-consuming process, make incremental publishing possible, and others.
  • Matt SullivanMatt Sullivan Posts: 1
    via Wordpress
    Great article, Mark.

    I like the "The primacy of conversation" section in particular.

    I see social media (conversation-based technical communication) as much more than marketing hype, but I've struggled for quite some time to explain why I think that social media and tech comm go hand-in-hand. You quantified it in just 2 paragraphs!
  • Sarah MaddoxSarah Maddox Posts: 2
    via Wordpress
    Hallo Mark
    Great article! It's an invitation to conversation in itself. I love the idea of changing the name of the tech pubs department to technical conversations. So much of what I do these days is different from the traditional tech writing. For example, answering questions on forums, writing blog posts, and presenting webinars. Yet they are all user assistance and all tech writing. And yes, there's a good dose of marketing in there too. You're spot on when you say the change in tech comm is already happening. It's up to us to surf the wave of change.
    Cheers, Sarah
  • John LimonJohn Limon Posts: 1 ✭✭
    via Wordpress
    With the user becoming more savvy and comfortable with technology and with the cost and availability of the technology allowing more to use them, new avenues for delivering the information are now here that were not just a few years ago. Recent conversations with colleagues and users just underline this new world where users now have elevated expectations with how they want to receive and use the information products being created.

    Today, users want information that can be quickly and easily found, annotated, customized, and shared. As always, be sure the information is accurate and timely. Produce it in a way that meets standards for clarity, grammar, style. Be sure it fits and takes advantage of whatever media it rides on. Oh, while you're at it, information should also educate, engage, and entertain. Somewhere in there, we must acknowledge that all this work has to happen in the context of a product's life cycle.

    Will this new doctrine address all these needs and expectations? Are today's and tomorrow's technical wri...err...communica...errr...conversationalists ready for this? I certainly hope so.
  • Larry KunzLarry Kunz Posts: 15
    via Wordpress
    I agree with pretty much everything you've said here, Mark. A great deal of it sounds like what I read in Content Strategy articles: integrating with the product lifecycle; emphasizing conversations over publications. Yet you also seem to be saying that technical content is different from other content (marketing, etc.), so that there will still be a clear boundary between "Tech Comm" and other kinds of communication. I think that the silo walls are coming down, and I think I understand why Scott and Jack are saying that we should call ourselves something else.

    You also say, very convincingly, that today's business needs will bring about this new doctrine almost by necessity. With all that, though we still have many clients who call and ask us to help them create PDFs. It's not just the tech pubs managers who don't get it. For at least a little while longer I think that many of us will have to work with our feet firmly planted in both worlds.

    So am I ready to put "Technical Conversationalist" on the top of my CV? Dunno. Got to think about that one.
  • Marcia Riefer JohnstonMarcia Riefer Johnston United StatesPosts: 7
    via Wordpress
    Insightful and inspiring, as usual, Mark. I'm with Sarah O'Keefe on needing this template:

    “Another brilliant article by Mark Baker: /insertlink/”

    A few favorites:
    - "bumph"
    - "failure to respect the conversational standards of immediacy, personality, and frankness"
    - "it is not about publications, it is about communications, and that, today, means conversations"

    I appreciate your emphasizing the ongoing relevance of the word "writer." Command of the language is the corest of core competencies.

    Proud to be a technical WRITER--
    Marcia
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Pamela, thanks for bringing up continuous publishing. I agree that it is going to be a vital part of the new doctrine of technical communications. I believe that conversation will assume the central role in tech comm, but publishing will remain an important supporting tool, and as such, publishing has to adapt itself to the way knowledge accumulates through conversation after the product has entered the market.

    More broadly, I think that we have to recognize an information cycle that exists within the overall product cycle, and the cycle of a product category. Information about a product category grows on the broadest arc. Within that arc, the release of particular products is an event that accelerates information growth, and for each product, the release of new versions is an event in the arc of that products information life cycle, but it is not a beginning or an ending event. We need to be able to publish continually to align with the growth curve of information.

    We also need to recognize when contributing to the information growth curve pays the biggest dividends for the company, when to throw all our resources at it, and when to step back and let it develop and grow on its own.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Scott, isn't it interesting that, after we have been told for so many years that writing for the web requires brevity, it is turning out to be the place where you are free from artificial word limits and can make your content as long as it needs to be.

    I agree with you about the terminology engineering. Changing what we call ourselves will not change who we are, as the quote from the Cluetrain Manifesto emphasizes. A change in doctrine is not a change in terminology. If people rechristen their departments "Technical Conversations" and then carry on as usual under the old doctrine, nothing will change (at least until the pink slips are delivered). If they keep calling themselves "Technical Publications", but transform what they do and how they work, that will change what the words "technical publications" mean to the rest of the company.

    My view, though, is that this is not a change we actually have any choice about. If we are reading the tea leaves correctly, the market will force a change. The question is, will it be the people now in technical communications departments across the world who remake themselves and their doctrine in obedience to the market, or will the new doctrine be created and proclaimed by the people who are brought in to replace them after they are laid off.

    Everyone is in charge of their own career, but no one is in charge of the market.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Hi Sarah,

    I agree completely, publication velocity is critical. If conversation is primary, and publication secondary, publication has to work at the speed of conversation. As currently practiced though, the publication event is rather like a wedding day. It takes months of planning, costs large amounts of money, disrupts the lives of everyone associated with it, and is executed in a kind of desperate panic lest any missed detail should spoil the immortal memory of the great day.

    We can't go on like this, and yet it seems that our tools and are processes are still being designed with this kind of wedding day publication in mind. Even when people are working in topics and content management systems, the publication event requires that new work be halted, and every topic brought into perfect readiness for the great day. At all other times, the systems is considered to be in an unpublishable state.

    What we need is a system that is always in a publishable state, and in which publication is not a great event, but a normal part of everyday life. One of the things that concerns me about DITA is that its map-based system of organization biases it strongly towards the wedding day style of publication. (I think it would not be entirely unfair to say that DocBook represents tech comm 1.0, that DITA represents tech comm 2.0, and that SPFE (SPFE.info) represents tech comm 3.0.)

    Wikis, in their original conception, represent much more of a publication-as-an-every-day-event model, though at the price of limited opportunities for automation. And yet, from what I am seeing in the forums, it seems as if a lot of groups are actually working hard to enforce a wedding day style of publication on their wiki system. (I'd love to hear Sarah Maddox's take on this.)
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Matt, it is certainly much more than marketing hype. Technical communications as conversation goes back to Usenet (in Internet terms -- it goes back to the agora and the apprenticeship system IRL). The difficulty always seems to be to convince people that this is not a new idea that we should implement, but and old idea that we should participate in.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Hi Sarah. I think you are one of the relatively small group of technical communicators who could make the change to "Technical Conversations" today and fully justify it in terms of what you are already doing.
  • Andrea WengerAndrea Wenger Posts: 1
    via Wordpress
    Excellent article, Mark.

    I hope, though, that whatever new doctrine emerges will recognize that technical communication is not limited to high-tech industries. Some companies manufacture products that may need to be installed in locations with no electricity, no wifi, and no cell phone service. So for now, these companies must still provide paper documents containing all the information that the customer needs in order to install the product safely and correctly. The only conversation going on will be with another guy on the job site.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Hi John. I'm not so sure that user's demand are really so unreasonable as you paint them. They certainly want the immediacy of a conversation, but I don't believe that they demand the polish of a publication out of every interaction with an individual.

    It may perhaps be our own doctrine that makes the demands seem so difficult to meet. We assume that we are being asked for more and more immediacy and interaction, without any corresponding relaxation of prior requirements. We may feel that we are being asked, to borrow the metaphor I used above, to throw a wedding every day. But I think most users simply want to meet for coffee. They don't need you to show up in a tuxedo with champagne and a cake. They just want you to show up and talk.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Hi Larry,

    I agree, it is not just the tech pubs managers who don't get it. Some who do get it are stymied by product managers who don't get it and don't want to think about it. Documentation, to them, is just a check-box item on the way to meeting a release date. The hard thing is that when the company does wake up to the need to engage with its customers in a whole new way, and demands that it happen immediately, it is the tech pubs manager who will take the fall, not the product manager who stood in the way of their making the change.

    What I think we can do for customers today is to provide them with systems that will support both wedding-day PDFs today, and continuous high-velocity publishing tomorrow. Alas, that is not a standard I think most tools being deployed today fully meet, and even those tools that might be able to meet is are not being deployed and configured in a way that will make it possible when the time comes.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Hi Marcia.

    My feeling (and I hope it is not wishful thinking) is that in the future the debate about whether one should be a *technical* writer or a technical *writer* will be finally resolved in favor of *technical writer* (and that the *Writer* part of that will be universally recognized to mean one who communicates effectively in text, not one who possesses a princess-and-the-pea sensitivity to misplaced semicolons).
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Andrea,

    I too hope that the new doctrine will better recognize just how diverse the field is, and how diverse the products and the users we serve. I'm not sure if it works that way though. I suspect that the doctrine of a profession inherently arises from the practice of the majority at the expense of the outliers.

    Happily, though, this is, and I believe will remain, a professions for the well educated and adaptable, rather than for the narrowly trained and certified, and the educated and adaptable are very able to work successfully as outliers -- and even to enjoy it.
  • Scott WilsonScott Wilson Posts: 1
    via Wordpress
    Mark,

    After reading both Jack Molisani and Scott Abel's Intercom article titled "Tech Comm 2.0: Reinventing our Relevance in the 2000s" and your follow-up article, I felt vaguely unsettled. Both are excellent articles, thoughtfully written and well researched, but neither quite "hit the nail on the head" for me.

    To get to the bottom of my unsettled feeling, I asked: "What is it that I think I do well?" (Some who know me might dispute the "well" portion, but let's move on.)

    The answer I came up with is: "I learn a new product to the extent that I can teach it to others, then disseminate the information I've learned to educate my audience to the extent they require."

    I believe this statement encapsulates what I do while being general enough to allow for a variety of circumstances.

    For example, when I say "learn a new product", I mean to gather data, to become a subject matter expert, by whatever means available; generally, those means could be reading about the product, talking to the engineer who created the product, talking to someone who knows the product better than I (a big thank you to all the QA folks who've helped me over the years!), or using the product myself. This learning process could take anywhere from a few minutes to many months, depending on a variety of factors.

    When I say "to the extent that I can teach it to others" I'm suggesting a level of understanding much greater than what is needed for me to just use the product. There's a big difference between using a product yourself and teaching it to someone else. Ask anyone who's had to teach a class or give a presentation at a conference; as far as I know, the adage of 10 minutes of preparation for every one minute of presenting still holds.

    When I say "disseminate the information", I mean to get it to my audience in the best format based on my understanding of their needs. Traditionally this has meant, for me, printed guides, man pages, PDF documents, Windows/Mac/Linux/mobile device online help, FAQs, videos, Web pages, Knowledge Bases, support forums, and so on.

    When I say "to educate my audience," I mean to get them to have as clear an understanding as I do of that portion of the product they want to know about. Again, this is based on my understanding of their needs.

    And when I say "to the extent they require," I mean that however great my understanding is of the needs of my audience, it is never going to be 100 percent, and thus no matter how much educating I provide at a particular point, more will be needed down the line. This could be as little as the clarification of a point or as much as an entirely new document with brand new content.

    So now that I think I know where I stand, on to the questions I asked myself after reading the two articles.

    Question 1: Do I agree with Jack and Scott's skills analysis?
    Answer 1: Mostly. I would like to call out one skill they cover in their Critical-Thinking Skills section, which they call "What do our customers need?" I'd like to call it Audience Analysis and give it more prominence. Much of what I produce and how I produce it is based on my analysis of the needs of my audience. If my audience analysis is bad, none of those other skills will prevent me from delivering content that does NOT meet the needs of my audience. It may be on time, in budget, and grammatically correct, but if it doesn't meet the needs of my audience, I've failed. Talk-show hosts and lawyers preparing for a jury trial do the same thing, so I think this skill applies outside our field.

    Question 2: Should I stop calling myself a "technical writer"?
    Answer 2: Maybe. No one at parties understands it, so maybe it's time for something new. On the other hand, I don't have anything better. I've heard User Assistance Professional, Information Developer, User Education Specialist, Technical Communicator, and others. None quite captures the whole spectrum of what we do. Business Analyst makes me cringe. And I'm pretty sure Solver of Content-Related Business Problems isn't going to fly with anybody. One thing in favor of keeping Technical Writer: it has its own entry in Wikipedia. I do agree, by the way, with Jack and Scott's point that Whatever We Call Ourselves, we need to elevate our reputations as individual contributors, increase our spheres of influence, and make sure management understands the value we add.

    Question 3: Do I agree with Mark that I need a new doctrine of technical communication based on the written conversation?
    Answer 3: Most definitely, yes and no. No, because what I do well (see way above; sorry for the length of this thing, btw), is ideally suited to the new conversation doctrine, as I understand it from your article. But yes, because few companies, in my opinion, are going to allow their technical writers to be the people who "create information swiftly and disseminate it instantly." Why? "Because they just write the manuals." Is it possible for one or more technical writers to convince their management that the company needs someone or a group to create information swiftly and disseminate it instantly, then convince them to let a technical writer do it? Possibly, in a small company where the technical writer is trusted as a subject matter expert and the Marketing department is not trusted to do the job or is extremely overworked. Analogy: I'm thinking along the lines of the response to a hostage situation: there is one police spokesperson from whom the press gets the official word of what's happening. Anyone else can speculate as much as they want, but the "official word" comes only from that police spokesperson. A technical writer who really knows their stuff could be a Product Spokesperson.) So maybe what we need to do is to convince our companies to create the position of Product Spokesperson, and then convince them to give the job to one of us instead of someone in Marketing. And then when pigs start flying, maybe they'll give us all rides to work.

    Maybe Solver of Content-Related Business Problems isn't going to fly as our titles, but changing the name of our department to Technical Conversations and then showing our companies what that means just might help our management start to understand our value and help us start to meet the needs of a changing "technical publications" world.

    Scott Wilson
    sjwilson42@gmail.com
  • Frank BuffumFrank Buffum Posts: 1
    via Wordpress
    Well said, Mark!
    Both the article and the ensuing conversation.
    I'm with Andrea on recognizing the diversity of the needs. We need to be able to think forward to serve the world of an engaged, technically advanced conversation which we moderate. But that does not mean the users, and clients who have simpler use cases (like an offline, printed instruction) can be marginalized or discarded. Some of those use cases are, for example, factories in China that are winning more business by their low pricing (partly based in using low- or no-tech solutions whereverthey can get away with it). If our content is out of their reach, and our company thus cannot work with them, then we cede a competitive advantage to the business that generates "old-thinking compliant" material alongside its "intelligent content."
    As you put it, we must "support both wedding-day PDFs today, and continuous high-velocity publishing tomorrow. " and I note your next , well chosen word... "Alas."
    Staying (or becoming) adaptable is good practice. The occupation title is always subject to interpretation. No matter if it's tech writer, content wrangler, enterprise communication evangelist, half the people seeing or hearing it either make up their own definition and don't tell us, or, if we're lucky, ask "so what does that mean?"
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Hi Scott,

    I agree that there is a real danger for people currently in the professions that companies will not think of them as the people to fill the emerging technical conversation roles. I wrote a blog post a while back titled "Want Respect? Get out of Publishing" (http://everypageispageone.com/2011/12/29/want-respect-get-out-of-publishing/) in which I argued that as long as we are seen as the publishing people, we won't we seen as technical peers.

    One reason for tech comm folk to take a lead on this is so that they will be candidates for these new roles as they are created. We need to reinvent ourselves not in order to change the world, but because the world is changing and leaving us behind.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Hi Frank,

    I agree, we will need to meet a variety of needs for the foreseeable future. But if we really create intelligent content, that won't really be an issue. Sufficiently intelligent content can always be dumbed-down to wedding day PDFs (though without the wedding day hysteria).

    Speaking of outsourcing to low cost markets, it is clear that a lot of the wedding-day PDF work is being outsourced and off-shored. The way to keep that work at home is probably to create sufficiently intelligent content that it can play both the continuous high-velocity publishing role needed to support conversation-based tech comm, and also create old media outputs as and when required.
  • Jonatan LundinJonatan Lundin Posts: 4
    via Wordpress
    Hi Mark,
    Thanks for a well written article. It summarizes the change happening - going from a simplex, broadcasting kind of a model, to a duplex communication model. I heard someone classify what we do (techcom) as mass communication.

    There are of course many undiscovered territories in this new landscape. First of all, I believe that it is worth pointing out that the change is happening faster in some areas and not at all in some other. Compare worldwide used consumer gadget or high tech niche industrial products sold on a very specific market, where users are reluctant to using computers to find information (yes, such markets exists). I read somewhere that half of the population on earth has never used a phone (not even a stationary phone). But, I’m convinced that the change will happen to all sooner or later.

    To me, it all boils down to understanding the behaviors and strategies of people using technical artifacts. And combine that understanding with the communication possibilities the web allows us to do. Users are active, goal oriented and sense making human beings. The primary goal of users is to use a product to solve a problem, need or requirement. When users need information to use it properly, they tend to evaluate the options available, and which options that gives the best output given the energy they put in. This is described by Zips principle of least effort.

    When searching for information, human tend to first consult as human like sources as possible – and a traditional manual (publication) is very unhuman. If users can find the answer to a question from an online forum instead of reading the whole manual, they maybe have saved some effort. And since the means of communicating through the web gives users among many things a possibility to save effort, techcom industry must conform and adapt since the web will not go away.

    But again, I think we over simplify; human behavior is very diverse. There are methodical users who actually do not dare to touch a product without learning and reading a paper book about it.

    The motto of the 1933 Chicago World’s Fair was “Science finds, industry applies, man conforms.” which the existing techcom doctrine sort of still lives under. Maybe the new techcom doctrine should be: “Users converse, industry studies, technical communicators conform”.
  • via Wordpress
    It's about conversation. Let's converse!...

    ...
  • Ellis PrattEllis Pratt Posts: 3
    via Wordpress
    This chimes a lot with what we've been saying.

    I think it's important to highlight that *some* products are no longer "technical". For these, we need a new approach, new business benefits etc. Other products will remain "technical" and the current approach to technical communication is still valid. If you look at Facebook, it adopts one approach for providing user assistance to end users and a different, more traditional, approach to would-be advertisers.

    I am still unsure about the future being truly conversational - a dialogue between two+ equal parties. Conversations are essentially oral - they have a rhythm, they repeat. I know a number of traditional storytellers and I suspect their approach may be a better model: there is a "teller" of the information who responds to questions from the audience as the story is told - more questions and commentary than a pure conversation. The difference is: there's a primary teller, the core information stays the same, but it can adapt to the audience. Writing and speaking differ - writing is much more succinct and efficient.

    I'm optimistic for the future as identifying the problem is the first part of identifying the solution. I think we're seeing a better understanding of the problems with technical communication and some innovative solutions. The move to mobile may well force significant change onto the User Assistance - a healthy shove towards new approaches.
  • Anne GentleAnne Gentle Posts: 1 ✭✭✭
    via Wordpress
    Great article Mark, really thought-provoking, and I've been having these thoughts firing in my brain for years now which prompted me to tagline my blog "Documentation as Conversation."

    One quote I pull and take note of is "Core reference information has been neglected for years because current tech comm doctrine does not have a place for it." API writers are highly valued for their ability to create valuable reference information. The beautiful API reference sites being made at Twitter[1] and Flickr [2] are testament to the fact that some companies do not neglect this need and excel at providing reference information.

    What I also see with OpenStack documentation is the struggle for the documentation to keep up with fast paced code - no "writing team" could keep up, instead a collaborative community and some automation and continuous integration (and yes publishing) are the only way to even attempt to maintain trust in the docs through updates. So, to Sarah O'Keefe's point, "close the gap between tech comm and readers" - I'd also add that we need to close the collaboration gap between tech comm and development (makers). I've bet my career on this collaboration path and it has been an amazing journey. Conversation and community, indeed. [3]

    1 https://dev.twitter.com/docs/api
    2 https://secure.flickr.com/services/api/
    3 http://justwriteclick.com/book
  • Jonathan BakerJonathan Baker Posts: 1
    via Wordpress
    I agree that a new model is needed. However, that does not mean the values change. I expect authorative, technically correct, grammatically correct, and complete communications. I am finding crowd-sourced documentation to be of limited worth, because I don't know who wrote it or why. And, more importantly, I don't have any way of knowing if it is correct. Having to wade through piles of crowd-sourced information to find the piece I need is generally a waste of good time. Particularly in the case of software. I want the vendor to tell me how to use the product.

    That said, I do find that sometimes I can learn more from other users, rather than the vendor, simply because most vendors don't use their own products in the creative ways that users might.

    Contradictory, you bet. That's what makes it interesting.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Ellis, I agree that many products are still "technical", in fact, I think the number of technical products is growing continually. But most of those technical products are being sold to technical people. I think it is safe to say that the normal state of affairs, over centuries of technological development, is that non-technical (that is, intuitive, easy to use) products are sold to non-technical people, and technical products are sold to technical people, and that non-technical people generally become technical through some kind of formal or informal apprenticeship program.

    The tech comm doctrine of the last three decades was created by a disruption of this pattern, a period in which large numbers of technical products were being sold to non-technical people and there were not enough qualified mentors available for those people to apprentice under, creating an extraordinary need for tech docs for novices. I'd agree that that disruption has not entirely disappeared yet, but the fact that the Web has made mentors available from around the globe means that its affects are less keenly felt. The appearance of the Web is why we can't simply go back to Tech Comm as it was before the tech boom.

    You make an interesting point about conversation. I'm not sure if I agree that a conversation is by nature between equals, though I suppose it depends on what we mean by equals. Certainly I don't think we can deny that an exchange is a conversation simply because more information flows in one direction than the other. That said, I agree that communication over the Internet does not work the same way as a private conversation. Since this article appeared I have taken to describing the Web as a colloquium rather than a conversation. (http://everypageispageone.com/2012/05/04/i-am-a-content-strategist/) I think the word colloquium captures more of the sense of something between a conversation and a publication that is closer to the character of the Web.
  • mbakeranalectambakeranalecta CanadaPosts: 53
    via Wordpress
    Hi Anne. Thanks for the comment. I am glad someone picked up on the core reference piece, which is something I regard as just as important as anything else I talk about in the article. I agree that there are some real shining examples of API documentation out there -- enough to really highlight the deficit the exists so many other places.

    Your juxtaposition of Sarah's point about closing the gap between tech comm and readers and your own point about closing the gap between tech comm and development is interesting because it to close both gaps is also to close the gap between development and readers. Tech comm has tended to regard itself as necessary buffer between development and the reader, whereas this suggests that tech comm's role is to be a thin and porous membrane between development and the reader.

    Certainly, to achieve that, tech comm will need a tools that support collaboration, automation, and continuous integration, but before that, it will need a new doctrine of technical communications.
«1
Sign In or Register to comment.