Comments on: The Case of the Stolen Documentation http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/ The Latest Trends in Technical Communication Sun, 27 May 2012 07:07:36 +0000 hourly 1 http://wordpress.org/?v=3.3.2 By: Sharing our source files with other companies « STC Europe SIG http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-163776 Sharing our source files with other companies « STC Europe SIG Mon, 04 Oct 2010 11:37:11 +0000 http://www.idratherbewriting.com/?p=5526#comment-163776 [...] this year, Tom Johnson in his blog “I’d Rather Be Writing” discussed the issue of documentation ownership. He had recently handed over the source files of several manuals he had done to an internal client [...] [...] this year, Tom Johnson in his blog “I’d Rather Be Writing” discussed the issue of documentation ownership. He had recently handed over the source files of several manuals he had done to an internal client [...]

]]> By: Matso Limtiaco http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-148248 Matso Limtiaco Wed, 03 Feb 2010 00:58:35 +0000 http://www.idratherbewriting.com/?p=5526#comment-148248 Our department doesn't create documentation for external clients, but we have had a couple of online Help systems "hijacked" by well-meaning but poorly trained software engineers. Reading between the lines, I think those engineers were trying to bypass the standard procedure for having TechComm write the online Help (read as: software project manager didn't budget for it). I'd never seen a well-written online Help system get turned back into an acronym-filled, menu-descriptive specifications document before! Our department doesn’t create documentation for external clients, but we have had a couple of online Help systems “hijacked” by well-meaning but poorly trained software engineers. Reading between the lines, I think those engineers were trying to bypass the standard procedure for having TechComm write the online Help (read as: software project manager didn’t budget for it). I’d never seen a well-written online Help system get turned back into an acronym-filled, menu-descriptive specifications document before!

]]> By: Michelle Newcome http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-148188 Michelle Newcome Thu, 28 Jan 2010 23:10:38 +0000 http://www.idratherbewriting.com/?p=5526#comment-148188 I used to get very proprietary about my manuals and as 100% of what I do is for clients I can't exactly demurely decline when they want their source files. Two things happened in 2009 that changed my opinion on releasing files to clients. The first was a disaster for my client - a large restaurant chain. They had an internal person do their operations guide and then allowed it to get 5 years out of date. When they wanted me to create new material and incorporate the old material the only thing available were pdf copies - they didn't even have the ability to update their own recipes. This client had to go through the trouble of doing a large search for the long-gone employee to see if they had the files since they did not want to pay to convert the pdf files. The second instance was a new client. I happily turned over their source files and they promptly totally blew them up by trying to change the formatting and not understanding the underlying structure. I now am on a document maintenance retainer with them. Sometimes letting your client make their own mistakes is actually beneficial to their understanding that documentation is not in the category of glorified-typing-pool product. I've gone to building in a teaching component into my project prices and I'll spend time with my clients teaching them how to maintain their own docs. I used to get very proprietary about my manuals and as 100% of what I do is for clients I can’t exactly demurely decline when they want their source files. Two things happened in 2009 that changed my opinion on releasing files to clients. The first was a disaster for my client – a large restaurant chain. They had an internal person do their operations guide and then allowed it to get 5 years out of date. When they wanted me to create new material and incorporate the old material the only thing available were pdf copies – they didn’t even have the ability to update their own recipes. This client had to go through the trouble of doing a large search for the long-gone employee to see if they had the files since they did not want to pay to convert the pdf files. The second instance was a new client. I happily turned over their source files and they promptly totally blew them up by trying to change the formatting and not understanding the underlying structure. I now am on a document maintenance retainer with them. Sometimes letting your client make their own mistakes is actually beneficial to their understanding that documentation is not in the category of glorified-typing-pool product. I’ve gone to building in a teaching component into my project prices and I’ll spend time with my clients teaching them how to maintain their own docs.

]]> By: Lisa Dyer http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-148023 Lisa Dyer Sun, 17 Jan 2010 20:50:44 +0000 http://www.idratherbewriting.com/?p=5526#comment-148023 Hi Tom, Thanks for the kind words:) Some good news regarding DITA2Wiki support for other wikis; a Maven plugin of the DITA2Confluence tool is under development, to be distributed as part of the Maven plugin of DITA OT. This work creates the appropriate architecture for supporting any wiki, enabling the DITA community to "plug in" their own import functions. GA is expected end of February. I'm hoping that someone will be inspired to contribute an import function for MediaWiki:) Cheers, - lisa Hi Tom,

Thanks for the kind words:)

Some good news regarding DITA2Wiki support for other wikis; a Maven plugin of the DITA2Confluence tool is under development, to be distributed as part of the Maven plugin of DITA OT.

This work creates the appropriate architecture for supporting any wiki, enabling the DITA community to “plug in” their own import functions. GA is expected end of February.

I’m hoping that someone will be inspired to contribute an import function for MediaWiki:)

Cheers,

- lisa

]]> By: Tom Johnson http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-147930 Tom Johnson Tue, 12 Jan 2010 21:29:08 +0000 http://www.idratherbewriting.com/?p=5526#comment-147930 Haitham, thanks for your comment. Retaining the source files seems like a good strategy for a number of reasons -- you protect yourself from brand misrepresentation, you maintain your role as the designated producer of the information, and you can keep a tight hold on style and structure. The only weakness is the lack of collaboration. If the SMEs have info you need, collaboration can be extremely helpful. If you already have the info, collaboration is unnecessary. Haitham, thanks for your comment. Retaining the source files seems like a good strategy for a number of reasons — you protect yourself from brand misrepresentation, you maintain your role as the designated producer of the information, and you can keep a tight hold on style and structure. The only weakness is the lack of collaboration. If the SMEs have info you need, collaboration can be extremely helpful. If you already have the info, collaboration is unnecessary.

]]> By: Tom Johnson http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-147929 Tom Johnson Tue, 12 Jan 2010 21:27:12 +0000 http://www.idratherbewriting.com/?p=5526#comment-147929 Lisa, thanks for adding the comment about the DITA2wiki plugin. I've seen you demo the plugin and have always been very impressed. My main hangup in adopting the plugin is that I'm using Mediawiki rather than Confluence, and I don't have my content structured in DITA. But I can see how this plugin would be incredibly helpful were a few variables in my situation different. Lisa, thanks for adding the comment about the DITA2wiki plugin. I’ve seen you demo the plugin and have always been very impressed. My main hangup in adopting the plugin is that I’m using Mediawiki rather than Confluence, and I don’t have my content structured in DITA. But I can see how this plugin would be incredibly helpful were a few variables in my situation different.

]]> By: iPhone Gratis http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-147919 iPhone Gratis Mon, 11 Jan 2010 21:50:19 +0000 http://www.idratherbewriting.com/?p=5526#comment-147919 Interesting post Tom, keep up the good posts! Interesting post Tom, keep up the good posts!

]]> By: Milan Davidovic http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-147912 Milan Davidovic Mon, 11 Jan 2010 15:32:31 +0000 http://www.idratherbewriting.com/?p=5526#comment-147912 Tom, Go here and read: http://www.scottburnham.com/files/Scott-Burnham-Hacking-Design-2009.pdf Now think about users taking over the information you produce vis-à-vis what Burnham says about hacking as "overcoming the limitations of an existing object, service or system which was set for one purpose, and finding an access point, intellectually or physically, where its original function can be expanded, altered, or improved to serve a new purpose or solve a problem". Do you see any of that happening with the documentation you hand over, either now or in future? Tom,

Go here and read:

http://www.scottburnham.com/files/Scott-Burnham-Hacking-Design-2009.pdf

Now think about users taking over the information you produce vis-à-vis what Burnham says about hacking as “overcoming the limitations of an existing object, service or system which was set for one purpose, and finding an access point, intellectually or physically, where its original function can be expanded, altered, or improved to serve a new purpose or solve a problem”.

Do you see any of that happening with the documentation you hand over, either now or in future?

]]> By: Isao http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-147891 Isao Sat, 09 Jan 2010 12:12:39 +0000 http://www.idratherbewriting.com/?p=5526#comment-147891 Tom, I have been reading your blog on and off for a few years and this is my first comment. Since I write some manuals myself I have also been stuck at the same situation, both on the stealing side and the stolen side. You are absolutely spot-on about the ownership thing - we should at least be lucky that we are dealing with more background stuff (manuals) than copies on the spotlight (web copies, packages, so on). I think one good thing in those situation is that nobody is trying to make things worse - they all believe they are doing the best for the outcome, even if it is identical with his personal preference. I am thinking open, collaborative editing might be the way thanks to you. We may have InDesign as a web-based app soon, which will make things more easier. Tom,

I have been reading your blog on and off for a few years and this is my first comment. Since I write some manuals myself I have also been stuck at the same situation, both on the stealing side and the stolen side. You are absolutely spot-on about the ownership thing – we should at least be lucky that we are dealing with more background stuff (manuals) than copies on the spotlight (web copies, packages, so on). I think one good thing in those situation is that nobody is trying to make things worse – they all believe they are doing the best for the outcome, even if it is identical with his personal preference. I am thinking open, collaborative editing might be the way thanks to you. We may have InDesign as a web-based app soon, which will make things more easier.

]]> By: Lisa Dyer http://idratherbewriting.com/2010/01/06/the-case-of-the-stolen-documentation/comment-page-1/#comment-147876 Lisa Dyer Sat, 09 Jan 2010 01:58:08 +0000 http://www.idratherbewriting.com/?p=5526#comment-147876 Dan, There is an open source solution for your use case. The project is called DITA2Wiki and it's available on SourceForge: http://sourceforge.net/projects/dita2wiki/ Download the latest DITA2Confluence binary distribution + User Guide PDF. Installing and importing the demo DITA content to the Confluence wiki should be easy and fast. You'll find some user reviews here (note that they describe some configurations that have changed, so be sure to follow the instructions in the latest User Guide PDF): * http://justwriteclick.com/2008/10/16/dita-meets-wiki-output-dita-to-wikitext/ * http://ffeathers.wordpress.com/2008/10/26/playing-with-dita2confluence/ BTW, DITA2Confluence also supports conref (reuse in DITA), which I don't think any other DITA-to-wiki solution does. The source text--the content being reused--is editable in the wiki output, but all reuse instances are read-only. Other nifty features include transforming metadata to wiki labels (useful for compatibility information and other categorization). If you have any questions, ping me at lisa dot dyer at gmail dot com. I can advise you on the round-trip aspects as well. Cheers, - lisa Dan,

There is an open source solution for your use case. The project is called DITA2Wiki and it’s available on SourceForge:

http://sourceforge.net/projects/dita2wiki/

Download the latest DITA2Confluence binary distribution + User Guide PDF.

Installing and importing the demo DITA content to the Confluence wiki should be easy and fast. You’ll find some user reviews here (note that they describe some configurations that have changed, so be sure to follow the instructions in the latest User Guide PDF):

* http://justwriteclick.com/2008/10/16/dita-meets-wiki-output-dita-to-wikitext/
* http://ffeathers.wordpress.com/2008/10/26/playing-with-dita2confluence/

BTW, DITA2Confluence also supports conref (reuse in DITA), which I don’t think any other DITA-to-wiki solution does. The source text–the content being reused–is editable in the wiki output, but all reuse instances are read-only.

Other nifty features include transforming metadata to wiki labels (useful for compatibility information and other categorization).

If you have any questions, ping me at lisa dot dyer at gmail dot com. I can advise you on the round-trip aspects as well.

Cheers,

- lisa

]]>