Re: [Framers] What causes documentation to fail

2016-05-20 Thread Steve Rickaby
Has anyone mentioned structure in this discussion? I don't mean structured vs. unstructured, I mean documentation design. Documentation can be basically sound, but rendered unusable by poor information design and/or lack of suitable navigation tools. This problem becomes geometrically worse as

Re: [Framers] What causes documentation to fail

2016-05-20 Thread Nancy Allison
Even if SMEs cooperate and tech writers are employed to do the work, these things can cause failure: 1. An inability to understand writing for an end user. I am still seeing writers dump every piece of technical information they receive into lengthy descriptions, but fail to shape

Re: [Framers] What causes documentation to fail

2016-05-20 Thread john . x . posada
en, Clint" <clint.o...@craneae.com> To: "Framers (E-mail)" <framers@lists.frameusers.com> Cc: "john.x.pos...@us.hsbc.com" <john.x.pos...@us.hsbc.com> Date: 05/20/2016 04:13 PM Subject: RE: [Framers] What causes documentation to fail 1. Ex

Re: [Framers] What causes documentation to fail

2016-05-20 Thread Lin Sims
ro.com" > <pe...@knowhowpro.com> > Cc: "Framers (E-mail)" <framers@lists.frameusers.com> > Date: 05/20/2016 02:31 PM > Subject:Re: [Framers] What causes documentation to fail > > > > Aren't bullet points subject to the "

Re: [Framers] What causes documentation to fail

2016-05-20 Thread john . x . posada
quot;pe...@knowhowpro.com" <pe...@knowhowpro.com> Cc: "Framers (E-mail)" <framers@lists.frameusers.com> Date: 05/20/2016 02:31 PM Subject: Re: [Framers] What causes documentation to fail Aren't bullet points subject to the "universal&q

Re: [Framers] What causes documentation to fail

2016-05-20 Thread john . x . posada
<framers@lists.frameusers.com> Date: 05/20/2016 02:57 PM Subject:Re: [Framers] What causes documentation to fail Sent by:calto...@gmail.com What are the risks if you have inadequate or missing documentation? Legally. How do your docs stack up against your competitors --

Re: [Framers] What causes documentation to fail

2016-05-20 Thread Robert Lauriston
Developers changing or adding features without informing the docs team. ___ This message is from the Framers mailing list Send messages to framers@lists.frameusers.com Visit the list's homepage at http://www.frameusers.com Archives located at

Re: [Framers] What causes documentation to fail

2016-05-20 Thread Liz Fraley
What are the risks if you have inadequate or missing documentation? Legally. How do your docs stack up against your competitors -- that's the first question a forensic documentation expert will ask if you end up in court. On Fri, May 20, 2016 at 9:48 AM, wrote: > >

Re: [Framers] What causes documentation to fail

2016-05-20 Thread Fred Ridder
m> on behalf of john.x.pos...@us.hsbc.com <john.x.pos...@us.hsbc.com> Sent: Friday, May 20, 2016 1:13 PM To: pe...@knowhowpro.com Cc: Framers (E-mail) Subject: Re: [Framers] What causes documentation to fail Thanks, Peter...but between you and me, I've never experienced a failed documentat

Re: [Framers] What causes documentation to fail

2016-05-20 Thread john . x . posada
com" <framers@lists.frameusers.com> Date: 05/20/2016 02:16 PM Subject:RE: [Framers] What causes documentation to fail I think you should pose the question as "What causes documentation to succeed?" Present the issue in a positive light, not a negative one. For exam

Re: [Framers] What causes documentation to fail

2016-05-20 Thread Etzel, Gary
mers] What causes documentation to fail Hi, guys...by end of today, I need to present to my manager a few bullet points for a presentation she is doing on Monday. The subject is: "What Causes Documentation to Fail" I've started with a few points: Not writing to a well-unders

Re: [Framers] What causes documentation to fail

2016-05-20 Thread John Sgammato
And there's the Miracle of Compound Interest - every time you add a new title, you then have to maintain it from version to version, so the workload grows even if the department doesn't. On Fri, May 20, 2016 at 1:27 PM, Catherine Woods wrote: > Documentation creep - like

Re: [Framers] What causes documentation to fail

2016-05-20 Thread Catherine Woods
Documentation creep - like every 4 months project management "thinks" up another document (or decides that original docs should be split into x) and expects the one assigned writer to pick it up Buy-in from project management on the documentation to be written that "don't change over time"

Re: [Framers] What causes documentation to fail

2016-05-20 Thread john . x . posada
whow...@gmail.com> To: john.x.pos...@us.hsbc.com Cc: "Framers (E-mail)" <framers@lists.frameusers.com> Date: 05/20/2016 01:10 PM Subject:Re: [Framers] What causes documentation to fail * Too many bullet points? * Or too few? On May 20, 2016 11:48 AM, <john.x.pos...@u

Re: [Framers] What causes documentation to fail

2016-05-20 Thread john . x . posada
.pos...@us.hsbc.com Cc: "framers@lists.frameusers.com" <framers@lists.frameusers.com> Date: 05/20/2016 01:00 PM Subject: Re: [Framers] What causes documentation to fail Starting with your first bullet, I'd ask what is she supposed to accomplish? Is this defending your job? The

Re: [Framers] What causes documentation to fail

2016-05-20 Thread John Sgammato
Starting with your first bullet, I'd ask what is she supposed to accomplish? Is this defending your job? The department? Looking for ways to improve? Maybe it's a rhetorical question and her audience already knows what they want to hear. Also, IMO bullet points invite argument. It's better to

[Framers] What causes documentation to fail

2016-05-20 Thread john . x . posada
Hi, guys...by end of today, I need to present to my manager a few bullet points for a presentation she is doing on Monday. The subject is: "What Causes Documentation to Fail" I've started with a few points: Not writing to a well-understood target audience Including too little or too much