Re: documentation best practices
At one time I had to write under development for the functionalities that have yet not been released. _ Dream -- the only movie you watch with your eyes shut Regards, NJ http://www.neerajjain8.com From: Jeff Coatsworth jeff.coatswo...@jonassoftware.com To: framers@lists.frameusers.com framers@lists.frameusers.com Sent: Tuesday, 6 December 2011 3:51 AM Subject: RE: documentation best practices It's called marketing ;) From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of hessiansx4 Sent: Monday, December 05, 2011 5:56 AM To: framers@lists.frameusers.com Subject: documentation best practices I could use some insight into a situation I haven't encountered before today: how does one best respond to a request (read: order) to include something in their product's documentation about a functionality that will not be released with the upcoming release (it will still be in development) but is hoped to be ready shortly (whatever that means) after the product is released. I've politely pointed out that industry best practice is to document what IS as opposed to what WILL BE and that certain liabilities might be incurred if promises are made and then something goes wrong. Any thoughts? ___ You are currently subscribed to framers as neerajja...@yahoo.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/neerajjain8%40yahoo.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: documentation best practices
What about inserting an asterik and saying Conditions Apply? _ Dream -- the only movie you watch with your eyes shut Regards, NJ http://www.neerajjain8.com From: Syed Zaeem Hosain (syed.hos...@aeris.net) syed.hos...@aeris.net To: Writer generic...@yahoo.ca; Jeff Coatsworth jeff.coatswo...@jonassoftware.com; framers@lists.frameusers.com framers@lists.frameusers.com Sent: Tuesday, 6 December 2011 5:45 AM Subject: RE: documentation best practices Not necessarily, but usually, I suspect. J In our case, in some of our API specs, we sometimes send out information to our Customers for review and comment, before it is “released into production” so to speak. We clearly identify this information as “Pre-Release” or “Draft”, with an introductory description that states very clearly that the functionality may not be available, and is subject to change when it is released … or withdrawn too! Works for us pretty well! Z From:framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Writer Sent: Monday, December 05, 2011 2:27 PM To: Jeff Coatsworth; framers@lists.frameusers.com Subject: Re: documentation best practices That's what I was thinking. It sounds more like marketing copy than user guide content. Nadine From:Jeff Coatsworth jeff.coatswo...@jonassoftware.com To: framers@lists.frameusers.com framers@lists.frameusers.com Sent: Monday, December 5, 2011 5:21:46 PM Subject: RE: documentation best practices It's called marketing ;) From:framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of hessiansx4 Sent: Monday, December 05, 2011 5:56 AM To: framers@lists.frameusers.com Subject: documentation best practices I could use some insight into a situation I haven't encountered before today: how does one best respond to a request (read: order) to include something in their product's documentation about a functionality that will not be released with the upcoming release (it will still be in development) but is hoped to be ready shortly (whatever that means) after the product is released. I've politely pointed out that industry best practice is to document what IS as opposed to what WILL BE and that certain liabilities might be incurred if promises are made and then something goes wrong. Any thoughts? ___ You are currently subscribed to framers as generic...@yahoo.ca. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to framers as neerajja...@yahoo.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/neerajjain8%40yahoo.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: Documentation Best Practices
Don't know if anyone has mentioned this, but the reason why you're not supposed to mention what will be in future versions is for legal reasons. You should not make forward-looking statements because the company could be held legally responsible for them. And since none of us can guarantee what the future holds, it behooves the company to state only what it can legally prove about its product. That being said, if you wanted to make assertions about future features, you could include a forward-looking disclaimer. See the Wikipedia article on this at http://en.wikipedia.org/wiki/Forward-looking_statement. Perhaps pointing this out to your managers would allow them to rethink this one. Lea Galanter Technical Editor Seattle, WA Confidentiality Notice: This email and any attachments are confidential and meant solely for the use of the intended recipient. If you are not the intended recipient any disclosure, copying, distribution or use of the e-mail or any attachment is prohibited. If you have received this email in error, please notify us immediately by replying to the sender and then delete this copy and the reply from your system. Thank you for your cooperation. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: documentation best practices
I think you are right about all of this. It's marketing fertilizer. If you have documented (via emails, memos) the risks, then you are covered, even if the company is not. Aspirational material needs that disclaimer that stock prospectives have ( and I don't think your boss will want that legaleseg) Grant - Nadine wrote: That's what I was thinking. It sounds more like marketing copy than user guide content. Nadine *From:* Jeff Coatsworth jeff.coatswo...@jonassoftware.com *To:* framers@lists.frameusers.com framers@lists.frameusers.com *Sent:* Monday, December 5, 2011 5:21:46 PM *Subject:* RE: documentation best practices It's called marketing ;) *From:* framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] *On Behalf Of *hessiansx4 *Sent:* Monday, December 05, 2011 5:56 AM *To:* framers@lists.frameusers.com *Subject:* documentation best practices I could use some insight into a situation I haven't encountered before today: how does one best respond to a request (read: order) to include something in their product's documentation about a functionality that will not be released with the upcoming release (it will still be in development) but is hoped to be ready shortly (whatever that means) after the product is released. I've politely pointed out that industry best practice is to document what IS as opposed to what WILL BE and that certain liabilities might be incurred if promises are made and then something goes wrong. Any thoughts? ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: Documentation Best Practices
Nicely put. Nadine From: Galanter, Lea lea.galan...@fticonsulting.com To: framers@lists.frameusers.com Sent: Tuesday, December 6, 2011 1:30:28 PM Subject: RE: Documentation Best Practices Don't know if anyone has mentioned this, but the reason why you're not supposed to mention what will be in future versions is for legal reasons. You should not make forward-looking statements because the company could be held legally responsible for them. And since none of us can guarantee what the future holds, it behooves the company to state only what it can legally prove about its product. That being said, if you wanted to make assertions about future features, you could include a forward-looking disclaimer. See the Wikipedia article on this at http://en.wikipedia.org/wiki/Forward-looking_statement. Perhaps pointing this out to your managers would allow them to rethink this one. Lea Galanter Technical Editor Seattle, WA Confidentiality Notice: This email and any attachments are confidential and meant solely for the use of the intended recipient. If you are not the intended recipient any disclosure, copying, distribution or use of the e-mail or any attachment is prohibited. If you have received this email in error, please notify us immediately by replying to the sender and then delete this copy and the reply from your system. Thank you for your cooperation. ___ You are currently subscribed to framers as generic...@yahoo.ca. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: documentation best practices
At 02:56 -0800 5/12/11, hessiansx4 wrote: I could use some insight into a situation I haven't encountered before today: how does one best respond to a request (read: order) to include something in their product's documentation about a functionality that will not be released with the upcoming release (it will still be in development) but is hoped to be ready shortly (whatever that means) after the product is released. I have just caught up with this thread, and was reminded of one of the nicest things that was ever said to me in my career as a tech author: 'I think we'll implement it the way you've described it in the user guide'. ;-) The legal point Lea made is important, I guess, and probably more so in the US. How about borrowing a tactic from the advertising industry and putting in a disclaimer to the effect that 'This feature may not be present in some versions of the software', omitting to mention that it's not present in any of them? ;-) It's been a long day... -- Steve ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: documentation best practices
As someone who both develops and documents software, I can only answer with a hearty Hear hear!. I think youre exactly right, and I hope you can get them to see the light. Good luck, Lea _ Lea Rush Software and Documentation Specialist Astoria-Pacific International http://www.astoria-pacific.com www.astoria-pacific.com http://www.a ph: 800-536-3111 fax: 503-655-7367 mailto:l...@astoria-pacific.com l...@astoria-pacific.com Please consider the environment before printing this email. `·.¸¸.·´¯`·.¸.·´¯`·...¸ º`·.¸¸.·´¯`·.¸.·´¯`·...¸º NOTICE OF CONFIDENTIALITY This communication is from Astoria-Pacific International and is intended to be confidential and solely for the use of the persons or entities addressed above. If you are not an intended recipient, be aware that the information contained herein may be protected from unauthorized use by privilege or law, and any copying, distribution, disclosure, or other use of this information is prohibited. If you have received this communication in error, please contact the sender by return email or telephone (503) 657-3010 immediately, and delete or destroy all copies. Thank you for your cooperation. From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of hessiansx4 Sent: Monday, December 05, 2011 2:56 AM To: framers@lists.frameusers.com Subject: documentation best practices I could use some insight into a situation I haven't encountered before today: how does one best respond to a request (read: order) to include something in their product's documentation about a functionality that will not be released with the upcoming release (it will still be in development) but is hoped to be ready shortly (whatever that means) after the product is released. I've politely pointed out that industry best practice is to document what IS as opposed to what WILL BE and that certain liabilities might be incurred if promises are made and then something goes wrong. Any thoughts? ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: documentation best practices
If they insist, I would make sure that it is well-marked as a future enhancement, perhaps is a separate section of the documentation. I just had a situation where a major aircraft maker (the one that does not start with a B) gave all sorts of very specific information about a software tool to make suppliers lives easier in a reference guide and on their website. When I went to track down the tool I discovered that it does not actually exist yet. Very frustrating. Clint Clint Owen | Sr. Technical Writer | Crane Aerospace Electronics | +1 425 743 8674 | Fax: +1 425 743 8113 From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of hessiansx4 Sent: Monday, December 05, 2011 2:56 AM To: framers@lists.frameusers.com Subject: documentation best practices I could use some insight into a situation I haven't encountered before today: how does one best respond to a request (read: order) to include something in their product's documentation about a functionality that will not be released with the upcoming release (it will still be in development) but is hoped to be ready shortly (whatever that means) after the product is released. I've politely pointed out that industry best practice is to document what IS as opposed to what WILL BE and that certain liabilities might be incurred if promises are made and then something goes wrong. Any thoughts? Check out the new Crane Aerospace Electronics Newsroom! http://newsroom.craneae.com Like us on Facebook! http://www.facebook.com/home.php?#!/pages/Crane-Aerospace-Electronics/163305413682908 We value your opinion! How may we serve you better? Please click the survey link to tell us how we are doing: http://www.craneae.com/ContactUs/VoiceofCustomer.aspx Your feedback is of the utmost importance to us. Thank you for your time. Crane Aerospace Electronics Confidentiality Statement: The information contained in this email message may be privileged and is confidential information intended only for the use of the recipient, or any employee or agent responsible to deliver it to the intended recipient. Any unauthorized use, distribution or copying of this information is strictly prohibited and may be unlawful. If you have received this communication in error, please notify the sender immediately and destroy the original message and all attachments from your electronic files. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: documentation best practices
It's called marketing ;) From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of hessiansx4 Sent: Monday, December 05, 2011 5:56 AM To: framers@lists.frameusers.com Subject: documentation best practices I could use some insight into a situation I haven't encountered before today: how does one best respond to a request (read: order) to include something in their product's documentation about a functionality that will not be released with the upcoming release (it will still be in development) but is hoped to be ready shortly (whatever that means) after the product is released. I've politely pointed out that industry best practice is to document what IS as opposed to what WILL BE and that certain liabilities might be incurred if promises are made and then something goes wrong. Any thoughts? ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: documentation best practices
That's what I was thinking. It sounds more like marketing copy than user guide content. Nadine From: Jeff Coatsworth jeff.coatswo...@jonassoftware.com To: framers@lists.frameusers.com framers@lists.frameusers.com Sent: Monday, December 5, 2011 5:21:46 PM Subject: RE: documentation best practices It's called marketing ;) From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of hessiansx4 Sent: Monday, December 05, 2011 5:56 AM To: framers@lists.frameusers.com Subject: documentation best practices I could use some insight into a situation I haven't encountered before today: how does one best respond to a request (read: order) to include something in their product's documentation about a functionality that will not be released with the upcoming release (it will still be in development) but is hoped to be ready shortly (whatever that means) after the product is released. I've politely pointed out that industry best practice is to document what IS as opposed to what WILL BE and that certain liabilities might be incurred if promises are made and then something goes wrong. Any thoughts? ___ You are currently subscribed to framers as generic...@yahoo.ca. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/generic668%40yahoo.ca Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to framers@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
