I highly recommend reading both posts. Because although I've read Anne Gentle's latest book, about how the social web impacts documentation, both posts were real eye-openers for me.
Tom ends his post with the following conclusion:
Using any of the standard authoring tools — Flare, RoboHelp, Author-It, Doc-to-Help — leaves you with the ridiculous model of a single author working from a single vantage point from a single organization trying to pull together an ocean of information. Because that model is untenable and unscalable, HATs will fade in favor of collaborative web-based authoring technologies.
I think both Tom and Michael are in essence right. But I don't think it will be the end for tools like Flare. I think they will continue to evolve like they have been over the last years. At least I hope they will.
What are your thoughts?
Have a great Sunday!
Cheers,
Patrick
Patrick Andriessen
Technical Information Consultant | WordPress Specialist | Certified MAD My Company | My Blog | Twitter
I agree to some extent. Flare has the tools to work as a multi-author CMS, but it lacks some features (such as output for standard platforms like Wikis, eLearning, proper change control) and the implementation of multi-authoring is in need of fixing, mainly the very limited native support of source control systems and the limitations in the command line build process (needing a fully licensed copy of Flare being just one of the issues). There are also plenty of document standards that are completely ignored (mainly ODF). I haven't tried master projects enough myself, but from what I read in the forums it isn't as straight forward and easy as one might wish for it.
Then again, when a company has extensive documentation needs the work is split up among the tech writers who each work on a portion where they have their biggest expertise. In the end the results are folded together.
The social web aspect (I call it "Wiki / SharePoint everything") is something not to be ignored, but also something that is just another option. There are plenty of cases where 'online' documentation is needed and a web based solution won't work and an intranet solution is often not an option for desktop apps. In my opinion, the social web approach is taken as a free for all, everyone can contribute, but many just shouldn't. Look at the social web sites and the quality of content.
Flare became a bit more "social" by introducing X-Edit, but it needs a few revisions to add in all the features and remove all the annoyances. Maybe it even needs a slightly different delivery method, X-Edit as a browser based system may work better for some. Additionally, as long as Mimic doesn't deliver rock solid eLearning content I don't think the MadCap Suite will make any inroads aside from traditional software documentation.
Lastly, MadCap needs to embrace other platforms than the very limiting Windows/.NET/IIS island. The major documentation sites often don't run on ASP.NET/IIS, but use more common platforms that are proven to be more reliable, easier to administer, and cost less in the long run.
OK, I reread the articles and this time really got hung up on a few points. The motion to use entire topics for reuse shows that the writer just doesn't get single sourcing and this thinks it sucks. If the chunk size is too big then yea, it won't fit into the 'mouth' of each writer. So the chunks have to be smaller (snippets, and some HATs exclusively use snippets rather than topics).
What really disqualifies Tom Johnson's comments are two things: the ignorance of the fact that the best tech writer IS also a subject matter expert. When a person writes about things he or she has not the slightest clue about he/she is nothing more than a formatter. Someone who makes it look pretty and knows how massage the awfully styled Word docs into a PDF. I never got the concept of tech writers writing anything without knowing what it is all about and how it all works. Sure, the SMEs are the ones who know the stuff, but often enough they cannot write well (there are exceptions!) and then the telephone game starts. How can a tech writer craft instructions without understanding exactly how everything works? I have come across plenty of helps that clearly show that the writer has no clue, which means I have no clue, which then means that I cannot use any of the instructions because the app looks and behaves differently. So yea, Mr. Johnson, immersion into the subject is necessary, after all that is your job as tech writer. And that no matter if your are working for the company or get hired for a project. I have to admit that I don't get the whole tech writer for temp hire approach. Hire one full time writer and when there isn't anything to document have him or her work in QA or support. That at least makes good use of the product training that the tech writer is supposed to get.
What really made me shake my head is the comment that developers only ever work on one project. Most development departments I was in had developers that specialized on particular elements of the application. While it is still important that everyone knows about the big picture so that they don't turn into SMIs (subject matter idiots) there is a real benefit to have some focus on UI development and get the training for that, some do all web services, others specialize in database related tasks, and some specialize in the "glue code" that joins the parts together. Aside from that, every developer has to know the industry and the business very well, otherwise the apps produced are nothing else than crapware. But due to the specialization the developers are working on multiple projects at the same time and have to juggle priorities and meet delivery deadlines, just like a tech writer would do. And in the same sense when having a team of tech writers they all have to have a general understanding of everything while each focusing on a specific subject or project. The need to be able to work on anything is necessary because people change jobs, retire, quit, etc. Business has to go on and with having internal resources to fill in the void quickly the disruption is minimized.
In the end the quality of the content matters. Nobody really cares if this or that HAT was used, if it was easy or not do craft the output, or if it was single-sourcing or not. Even within the company the tech writers are really the only ones who care about it. Anything that makes their lives easier is welcome. It saves time that can be spent on being a subject matter expert. Maybe not as much of an expert as the 'real' SMEs, but expert enough so that communication between SMEs and tech writer is not like talking to a wall.
But OK, if learning what you have to write about is asking too much while getting paid a good salary, that's your problem and management will eventually work that out for you (and you won't like it). And how to source what with which tool is an important decision, but it pales in comparison to deciding how to produce high quality content. Tools are just that, they are tools, they are devices to help one do the work, but they don't do the work for you and they don't fix your management issues. HATs may fade away, or better to say, they will have to morph into something that suits the changing processes - even after fads like Wikis, DITA, and SharePoint passed us.
Neil Perlin wrote a comment at the end of Tom's blog that I agree with (and it would seem you do, too, Patrick): HATs will evolve as they always have. It would take significantly more than the fading of "single-sourcing" to destroy the value HATs present. They were useful long before single-sourcing was a fad, and will continue to be useful, even if it fades away.
As for the idea that social networking / web 2.0 / etc. will become the new documentation...laughable. Very. These are certainly excellent supplemental materials, and can add a lot of value to documentation, but they will not replace it, at least not in many markets. The interesting question is how do we integrate these outside sources with our documentation? How does our documentation change because of it? I'm less interested in using them as reasons why single-sourcing will die, and more interested in specific implementations and best practices of integrating social content. For example, I've been kicking around the idea of a "wiki help" standard of some kind (and of course I'm not alone), but I very much see a place for HATs as well as primacy of information architects / tech writers / pick-your-title in starting, organizing, and contributing content.
The thing with social networking type of sites is that it requires a starting point. Imagine if there was no built-in help for Flare when it was launched. So a few people would have to be guinea pigs and would have to learn the software by trial-and-error. So as they posted, some info could be wrong because they're either guessing or it worked correctly for them but not someone else and the first poster got lucky.
I think social networking will enhance out-of-the-box documentation, but I don't think it will replace it, unless the sites are started by tech writers at a company and released at the same time as the software or whatever is released.
Lisa Eagles may soar, but weasels aren't sucked into jet engines. Warning! Loose nut behind the keyboard.
Lisa, Andrew and RamonS, thank you for your insightful comments. I like to put in my two cents in this discussion. I hope it makes sense and if not please don't hesitate to correct or ask me. Thanks a bundle!
RamonS, I agree with a lot that you are saying. I would also love to see MadCap embrace other technology platforms than just Windows / .NET and IIS. I think the feedback server has great potential to bring the community to MadCap managed / published content. Maybe the - still to come - Team Server - will be even better. But the fact that they will only work on IIS and SQL server is unfortunate. Unfortunate but not surprising as their strategic partner is Microsoft Corp. It is probably that alliance (and the great people at MadCap of course) that made it possible that Flare is already as mature as it is after only five years.
I do not work with ISS and SQL server and if you'd ask me, I would probably like something on Apache, MySQL and PHP. But alas, MadCap is just not there yet, but they will eventually. Andrew, I indeed do agree with Neil Perlin's comment at the end of Tom's post. HAT's will evolve.
When it comes to Single Sourcing, Re-use, Multi Channel Publishing, Database Publishing (or whatever someone decides to call it), I think it is an irrelevant discussion to determine whether or not it works.
Michael Hiatt makes a valid argument that Single Sourcing as it is sold by consultants and evangelists will not work as they will tell you. Valid, but I say: Duh!
When you talk to a DITA evangelist, of course they will tell you that DITA is great and solves all your documentation problems. And of course it doesn't. Because we live in a real world, where the planets do not always align properly for a magical and successful implementation of a - company wide - structured writing workflow to occur. But whoever said it had to be exactly that.
We can do 15%, and we will benefit. Or maybe do 40% or 60% and benefit even more (or maybe we'll even involve our customers and we'll benefit way beyond what we could have imagined). I agree with Lisa that social networks and the community will enhance the information that we produce, but that they will never replace it.
As far as the Single Sourcing Myth or Law discussion is concerned, I look at it this way: If I can use the same thing twice (or more) instead of once, I think it makes sense to do so. And if there are tools available (like Flare) that help me do that, great! End of discussion for me.
Now how about those Subject Matter Experts? RamonS, I totally agree with your statement that the best tech writer is also a SME. But...
I don't know how things work in the US, but here in the Netherlands hiring a full-time writer and have him do QA or support when he is not writing is as rare as a successful implementation of a - company wide - structured writing workflow. In a lot of companies that I've worked for writers were the first to be laid off during bad times and the last to be hired back during good times. It is one of those professions that are often hired on a temp basis and that makes it that they never can be true SME's.
Of course I get and need to learn a lot of the product I'm describing though (and so does Tom). And my writing expertise does provide a lot of value to the organization that hires me. So I don't think we should dismiss Tom's thoughts on the fact that he is “hired help" alone. But maybe I'm missing the point you are trying to make entirely RamonS, and then please accept my apologies.
At the end of the day it is us that make the great content and not the tools. But boy they do make my life a lot easier.
And now it is time for me to turn in for the night. Bye Y'all!
- Patrick
Patrick Andriessen
Technical Information Consultant | WordPress Specialist | Certified MAD My Company | My Blog | Twitter
NAPNAM wrote:Now how about those Subject Matter Experts? RamonS, I totally agree with your statement that the best tech writer is also a SME. But...
I don't know how things work in the US, but here in the Netherlands hiring a full-time writer and have him do QA or support when he is not writing is as rare as a successful implementation of a - company wide - structured writing workflow. In a lot of companies that I've worked for writers were the first to be laid off during bad times and the last to be hired back during good times. It is one of those professions that are often hired on a temp basis and that makes it that they never can be true SME's.
Of course I get and need to learn a lot of the product I'm describing though (and so does Tom). And my writing expertise does provide a lot of value to the organization that hires me. So I don't think we should dismiss Tom's thoughts on the fact that he is “hired help" alone. But maybe I'm missing the point you are trying to make entirely RamonS, and then please accept my apologies.
- Patrick
No need to apologize for anything. I think it is not a US versus Netherlands (Europe) thing, but it comes down to the individual company. Sure, users got used to craptastic docs over the years, so laying off the tech writers first won't hurt business as much as it cuts expenses. But that is exactly my point. Making a tech writer to be versatile and not just push him or her off into the formatter role makes in my opinion a lot of sense for a company. When I used to work at IR I did tech writing, QA, and level 3 support. All three areas of activity helped each other and made me to be one of the few who were kept on when the big round of layoffs came (we were about 35 and 6 were left). We had another tech writer who didn't do anything else than Frame and make stuff look pretty. I am sure he was up high on the list.
As a company, would you rather have a full time employee that knows what is going on in the business or just some foot soldier that doesn't give a damn because the engagement is over after 18 months? If they'd ask me to go into a production line or clean the screw machines, I'd have done that as well as long as there is a perspective of new software being made.
Documentation, especially online help, is an important part of software development. As a software company, that is a core competency and any MBA 100 level course drives home the point that you cannot outsource core competencies (unless you want your business to go down the toilet). Same deal with QA, how can anyone in their right mind want to outsource QA? Or even worse, outsourcing support????? Why on earth would any company want to have totally detached people talk to the upset customers? I think it makes almost more sense to outsource commodity software development. Another one of these never ever outsource jobs is front desk. Sure, it is not a core competency, but that person is the first one to answer the phone when people call. Why would one want to have a temp getting minimum wage do that job? Front desk should get at least as much of a salary as a senior lead developer does. Assuming the skills and talent is there.
From a viewpoint of the tech writer, wouldn't the tw want to know everything to do a better job and understand what is going on? So complaining that the new project would take months of studying is just plain wrong in my book. That is part of the job of a tech writer. Anyone else is just a measly formatter. That is the point I don't get in Johnson's post.
I think it is not a US versus Netherlands (Europe) thing, but it comes down to the individual company. Sure, users got used to craptastic docs over the years, so laying off the tech writers first won't hurt business as much as it cuts expenses. But that is exactly my point. Making a tech writer to be versatile and not just push him or her off into the formatter role makes in my opinion a lot of sense for a company. When I used to work at IR I did tech writing, QA, and level 3 support. All three areas of activity helped each other and made me to be one of the few who were kept on when the big round of layoffs came (we were about 35 and 6 were left). We had another tech writer who didn't do anything else than Frame and make stuff look pretty. I am sure he was up high on the list.
I agree that it probably comes down to the individual company. I also think that a lot of companies would like their own techpub department, but that reality shows (at least over here) that a lot of them don't have one. Why don't they have one? My guess is as good as yours.
What I do not agree with is that temp writers are just foot soldiers that do not give a damn. It is just not true, because this comes down to the individual tech writer. There are excellent tech writers working for companies directly as there are tech writers that do excellent work on a temp basis. And of of course the opposite is also true.
What makes tech writing on a temp basis so attractive for me is that fact that I get to learn so many different things. So yes, I do want to know everything to do a better job. So you won't hear me complaining about it, it is what makes tech writing so much fun for me.
That being said and although I enjoy the discussion...I think we are straying of the topic a bit
- Patrick
Patrick Andriessen
Technical Information Consultant | WordPress Specialist | Certified MAD My Company | My Blog | Twitter
I think the real issue isn't about tools at all. Tom writes that a customer of his was asking him to generate hundreds of pages of documentation on some pretty specialized subject matter (that he has no background in) in a matter of 2-3 months. Well, realistically that couldn't be done by one person no matter what tools or workflow you used. This customer has completely underestimated the magnitude of the task. It's a bit like saying nail-guns are destined to disappear because one carpenter can't use one to assemble a sky scraper in three months. The attraction of Wikis etc. in this case is that they lend themselves to collaborative work, enabling the writer to hand a lot of the writing tasks off to other people. Wellll.... if the customer was willing to hire a team of writers instead of a single writer and give them a realistic deadline you wouldn't have a problem then, would you?
Plus, lets consider a few other issues:
Getting SMEs to write the content is all well and good... as long as they can actually write. And as long as they actually do write, rather than saying "I have more important things to do, this is the tech writer's job."
With a Wiki, anyone who has access can update entries at any time. Soooo.... how do you handle sign off on the content? How do you ensure that what was entered at any given time is actually correct and consistent with the content in other topics? If the content in the Wiki is available to customers, this is critically important - if whoever updated the docs last got something wrong, the company could potentially be liable. In a traditional documentation system you can have the content vetted by management and legal when it's done, but in a Wiki there's never a "done" stage.
How do you manage context sensitive linking? Non-TWs aren't going to know how to link it (or even think about it, probably) while the TW won't have the familiarity with the content anymore to determine which topics to link where. And that's leaving aside the fact that no one currently has a way to do CSH links to a Wiki.
Ohhh, wait, I hear it now: "CSH is sooo old media, users just want to search for things now." Really? Anyone actually asked a user about that? Or did we just assume they prefer search because it's easier for us to deliver? Not to mention what happens when the 15 SMEs who are writing the content don't confer with one another to use consistent standardized terminology so you don't have one writer's topics using "open" and another's using "load" for the same process. That would never happen, would it?
The more I think about it, leaving documentation solely to users and SMEs makes as much sense as running an open-source development project without a project lead.
I'm going to stop now because this is turning into a rant
Until next time....
Kevin Amery
Certified MAD for Flare
The one advantage to a Wiki-type system is that people don't think of it as "help" the way we do. A lot of people won't think of going to the "packaged" help and searching for it. Instead they opt to Google for it. So in that situation, a Wiki might get more attention. On the other hand, if you put your help on the web, then it will turn up in a Google search. So if you think people are more likely to search the Internet to find their answers instead of go to your "packaged" help, then develop WebHelp (or better yet, WebHelp Plus) and put it on a publicly-facing web server so they can find the answers by Googling.
Lisa Eagles may soar, but weasels aren't sucked into jet engines. Warning! Loose nut behind the keyboard.
LTinker68 wrote:The one advantage to a Wiki-type system is that people don't think of it as "help" the way we do. A lot of people won't think of going to the "packaged" help and searching for it. Instead they opt to Google for it. So in that situation, a Wiki might get more attention. On the other hand, if you put your help on the web, then it will turn up in a Google search. So if you think people are more likely to search the Internet to find their answers instead of go to your "packaged" help, then develop WebHelp (or better yet, WebHelp Plus) and put it on a publicly-facing web server so they can find the answers by Googling.
This may work for OTS (Off-The-Shelf) software, but for industrial or business-to-business software, that is typically not reasonable. None of the developers want their documentation exposed to google (or to anyone except customers) because they don't want it to get into their competitor's hands.
