Re: [Framers] What causes documentation to fail

[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 documentation sets grow, especially 
for complex systems with many interacting components. Many years ago I worked 
with Hewlett Packard minicomputers (the HP1000 series, if anyone remembers 
those). These machines were ferociously good for their time, but the 
documentation was pretty dire. As the capability of the machines had grown, the 
documentation set had grown alongside them by merely adding new manuals, much 
as Nature evolved the human brain by adding new bits on top of old bits ;-)

There was no global view, so solving a technical issue often involved picking 
through multiple, thick, manuals that deal with older, newer, higher and lower 
levels of detail. I often found myself five or six deep in open manuals at the 
end of a happy day of debugging. I am sure this was very good for my mental 
training, but it was not an efficient way to work. I doubt if this was an 
isolated problem. 

I would be a lot richer now if I'd applied the same level of concentration to 
Unix systems, but sadly I merely became expert in an operating system that was 
soon to become obsolete. But the memory lingers: great hardware, awesome 
operating system, ghastly documentation.

-- 
Steve 
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[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 it for the concerns of the
   user.
   2. Omission of background and contextual information that is critical
   to understanding the current topic. Such information may be provided by
   a link to a different topic, but it must be presented somehow.
   3. Omission of this critical information: why the reader should care.
   What is the purpose of using the feature. What problem does it solve.
   What happens if you don't use it. What happens if you don't change the
   default values.
   4. Poor choice of graphics. I've recently been seeing huge screenshots,
   with no highlights, circles, callouts, nothing, plunked into the
   beginning of a procedure, evidently as some kind of establishing shot.
   The sprawling screenshot has no real purpose, but the reader has to
   puzzle over it for a minute before concluding that it is worthless. In
   addition, I've seen UI elements cropped so tightly that there is no
   location information. What's the point of a cutout of a radio button
   and label all by themselves? Give some hint as to where to find them.
   5. Poorly written sentences and weirdly flowing paragraphs. I'm sorry
   to say, there are tech writers with decades of experience who evidently
   have been able to keep employed because they have a technical
   background and talk easily with engineers. Their actual writing is
   awful.
   Hope this isn't too negative. But, let's be honest, an incompetent tech
   writer can produce many types of failure that result in an
   all-but-useless document. I've seen it.
   Happy Friday!
   --Nancy
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[john . x . posada]

Thanks...though not applicable here. This is for internal documentation for
inhouse systems. No product is being sold and no involvement with marketing
or sales..

John X Posada
SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
America Holdings Inc
330 Madison Ave., NY NY

 __ 





 Phone  
  Int: 212-525-5483 Ext: 646-735-1857   
 Fax
  Conference Bridge - 877-304-0052, Code 74809254   
 Email  
  john.x.pos...@us.hsbc.com 

 __ 
 Protect our environment - please only print this if you have to!   






From:   "Owen, 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. Executives who sign contracts that provide all product support
documentation for free.
2. Other executives who don't want to pay Tech Pubs to produce
contractually required documentation because they have not put it in their
budgets.

Clint

Clint Owen | Technical Writer Specialist | Crane Aerospace & Electronics |
+1 425 743 8674 | Fax: +1 425 743 8113

-Original Message-
From: Framers [mailto:framers-bounces
+clint.owen=craneaerospace@lists.frameusers.com] On Behalf Of Lin Sims
Sent: Friday, May 20, 2016 1:05 PM
To: john.x.pos...@us.hsbc.com
Cc: pe...@knowhowpro.com; Framers (E-mail)
Subject: Re: [Framers] What causes documentation to fail

I'd say that the biggest problem is having managers and SMEs who consider
documentation to be of little or no importance compared to their "real"
work, so their responsibility to provide information or answer questions or
perform reviews is ignored or skimped on.

On Fri, May 20, 2016 at 3:35 PM, <john.x.pos...@us.hsbc.com> wrote:

> I've never seen a documentation project fail because it had 10 bullets
> in it. :-)
>
> John X Posada
> SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC
> North America Holdings Inc
> 330 Madison Ave., NY NY
>
>  __
>
>
>
>
>
>  Phone
>   Int: 212-525-5483 Ext: 646-735-1857  Fax
>   Conference Bridge - 877-304-0052, Code 74809254  Email
>   john.x.pos...@us.hsbc.com
>
>  __
>  Protect our environment - please only print this if you have to!
>
>
>
>
>
>
> From:   "Fred Ridder" <docu...@hotmail.com>
> To: John X Posada/HBUS/HSBC@HSBC02, "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" 7 +/-2 rule? If so, 10
> bullets would be doomed to failure. But John's original list would be
> OK at
> 8 bullets.
>
> ;^)
> -FR
>
> ________________
> From: Framers
> <framers-bounces+docudoc=hotmail@lists.frameusers.com>
> 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 documentation project because 10 bullets was used. :-).
>
> John X Posada
> SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC
> North America Holdings Inc
> 330 Madison Ave., NY NY
>
>  __
>
>
>
>
>
>  Phone
>   Int: 212-525-5483 Ext: 646-735-1857  Fax
>   Conference Bridge - 877-30

Re: [Framers] What causes documentation to fail

[Lin Sims]

I'd say that the biggest problem is having managers and SMEs who consider
documentation to be of little or no importance compared to their "real"
work, so their responsibility to provide information or answer questions or
perform reviews is ignored or skimped on.

On Fri, May 20, 2016 at 3:35 PM, <john.x.pos...@us.hsbc.com> wrote:

> I've never seen a documentation project fail because it had 10 bullets in
> it. :-)
>
> John X Posada
> SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
> America Holdings Inc
> 330 Madison Ave., NY NY
>
>  __
>
>
>
>
>
>  Phone
>   Int: 212-525-5483 Ext: 646-735-1857
>  Fax
>   Conference Bridge - 877-304-0052, Code 74809254
>  Email
>   john.x.pos...@us.hsbc.com
>
>  __
>  Protect our environment - please only print this if you have to!
>
>
>
>
>
>
> From:   "Fred Ridder" <docu...@hotmail.com>
> To: John X Posada/HBUS/HSBC@HSBC02, "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" 7 +/-2 rule? If so, 10
> bullets would be doomed to failure. But John's original list would be OK at
> 8 bullets.
>
> ;^)
> -FR
>
> 
> From: Framers <framers-bounces+docudoc=hotmail@lists.frameusers.com>
> 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
> documentation project because 10 bullets was used. :-).
>
> John X Posada
> SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
> America Holdings Inc
> 330 Madison Ave., NY NY
>
>  __
>
>
>
>
>
>  Phone
>   Int: 212-525-5483 Ext: 646-735-1857
>  Fax
>   Conference Bridge - 877-304-0052, Code 74809254
>  Email
>   john.x.pos...@us.hsbc.com
>
>  __________________
>  Protect our environment - please only print this if you have to!
>
>
>
>
>
>
> From:   "Peter Gold" <knowhow...@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?
>
>
>
>
>
> **
> This message originated from the Internet. Its originator may or may not be
> who they claim to be and the information contained in the message and any
> attachments may or may not be accurate.
> **
>
>
>
>
> -
> **
> This E-mail is confidential. It may also be legally privileged. If
> you are not the addressee you may not copy, forward, disclose or
> use any part of it. If you have received this message in error,
> please delete it and all copies from your system and notify the
> sender immediately by return E-mail.
>
> Internet communications cannot be guaranteed to be timely, secure,
> error or virus-free. The sender does not accept liability for any
> errors or omissions.
> **
> SAVE PAPER - THINK BEFORE YOU PRINT!
> ___
>
> 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
> http://www.mail-archive.com/framers%40lists.frameusers.com/
> Subscribe and unsubscribe at
> http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> Send administrative questions to listad...@frameusers.com
>



-- 
Lin Sims
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[john . x . posada]

I've never seen a documentation project fail because it had 10 bullets in
it. :-)

John X Posada
SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
America Holdings Inc
330 Madison Ave., NY NY

 __ 





 Phone  
  Int: 212-525-5483 Ext: 646-735-1857   
 Fax
  Conference Bridge - 877-304-0052, Code 74809254   
 Email  
  john.x.pos...@us.hsbc.com 

 __ 
 Protect our environment - please only print this if you have to!   






From:   "Fred Ridder" <docu...@hotmail.com>
To: John X Posada/HBUS/HSBC@HSBC02, "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" 7 +/-2 rule? If so, 10
bullets would be doomed to failure. But John's original list would be OK at
8 bullets.

;^)
-FR


From: Framers <framers-bounces+docudoc=hotmail@lists.frameusers.com> 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
documentation project because 10 bullets was used. :-).

John X Posada
SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
America Holdings Inc
330 Madison Ave., NY NY

 __





 Phone
  Int: 212-525-5483 Ext: 646-735-1857
 Fax
  Conference Bridge - 877-304-0052, Code 74809254
 Email
  john.x.pos...@us.hsbc.com

 __
 Protect our environment - please only print this if you have to!






From:   "Peter Gold" <knowhow...@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?





**
This message originated from the Internet. Its originator may or may not be
who they claim to be and the information contained in the message and any
attachments may or may not be accurate.
**




-
**
This E-mail is confidential. It may also be legally privileged. If
you are not the addressee you may not copy, forward, disclose or
use any part of it. If you have received this message in error,
please delete it and all copies from your system and notify the
sender immediately by return E-mail.

Internet communications cannot be guaranteed to be timely, secure,
error or virus-free. The sender does not accept liability for any
errors or omissions.
**
SAVE PAPER - THINK BEFORE YOU PRINT!
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[john . x . posada]

Internal documentation ...no competitors.

John X Posada
SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
America Holdings Inc
330 Madison Ave., NY NY

 __ 





 Phone  
  Int: 212-525-5483 Ext: 646-735-1857   
 Fax
  Conference Bridge - 877-304-0052, Code 74809254   
 Email  
  john.x.pos...@us.hsbc.com 

 __ 
 Protect our environment - please only print this if you have to!   






From:   "Liz Fraley" <l...@caltonia.com>
To: john.x.pos...@us.hsbc.com
Cc: "framers@lists.frameusers.com" <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 -- 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, <john.x.pos...@us.hsbc.com> wrote:

  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 information
     Failure to bring documentation into the project early enough in the
     project
     Failure to establish a governance, review, and approval structure
     Lack of clear  roles and responsibilities
     Belief that “anyone can produce acceptable documentation”
     Lack of feedback early enough in the process to implement without
     wasting a large amount of work and/or affecting deadline
     Scope creep

  Anyone want to add more to the list?


  John X Posada
  SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
  America Holdings Inc
  330 Madison Ave., NY NY

   __





   Phone
        Int: 212-525-5483 Ext: 646-735-1857
   Fax
        Conference Bridge - 877-304-0052, Code 74809254
   Email
        john.x.pos...@us.hsbc.com

   __
   Protect our environment - please only print this if you have to!



  -
  **
  This E-mail is confidential. It may also be legally privileged. If
  you are not the addressee you may not copy, forward, disclose or
  use any part of it. If you have received this message in error,
  please delete it and all copies from your system and notify the
  sender immediately by return E-mail.

  Internet communications cannot be guaranteed to be timely, secure,
  error or virus-free. The sender does not accept liability for any
  errors or omissions.
  **
  SAVE PAPER - THINK BEFORE YOU PRINT!
  ___

  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
  http://www.mail-archive.com/framers%40lists.frameusers.com/
  Subscribe and unsubscribe at
  http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
  Send administrative questions to listad...@frameusers.com



** This
message originated from the Internet. Its originator may or may not be who
they claim to be and the information contained in the message and any
attachments may or may not be accurate.
**



-
**
This E-mail is confidential. It may also be legally privileged. If
you are not the addressee you may not copy, forward, disclose or
use any part o

Re: [Framers] What causes documentation to fail

[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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[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:

>
> 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 information
>Failure to bring documentation into the project early enough in the
>project
>Failure to establish a governance, review, and approval structure
>Lack of clear  roles and responsibilities
>Belief that “anyone can produce acceptable documentation”
>Lack of feedback early enough in the process to implement without
>wasting a large amount of work and/or affecting deadline
>Scope creep
>
> Anyone want to add more to the list?
>
>
> John X Posada
> SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
> America Holdings Inc
> 330 Madison Ave., NY NY
>
>  __
>
>
>
>
>
>  Phone
>   Int: 212-525-5483 Ext: 646-735-1857
>  Fax
>   Conference Bridge - 877-304-0052, Code 74809254
>  Email
>   john.x.pos...@us.hsbc.com
>
>  __
>  Protect our environment - please only print this if you have to!
>
>
>
> -
> **
> This E-mail is confidential. It may also be legally privileged. If
> you are not the addressee you may not copy, forward, disclose or
> use any part of it. If you have received this message in error,
> please delete it and all copies from your system and notify the
> sender immediately by return E-mail.
>
> Internet communications cannot be guaranteed to be timely, secure,
> error or virus-free. The sender does not accept liability for any
> errors or omissions.
> **
> SAVE PAPER - THINK BEFORE YOU PRINT!
> ___
>
> 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
> http://www.mail-archive.com/framers%40lists.frameusers.com/
> Subscribe and unsubscribe at
> http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> Send administrative questions to listad...@frameusers.com
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[Fred Ridder]

Aren't bullet points subject to the "universal" 7 +/-2 rule? If so, 10 bullets 
would be doomed to failure. But John's original list would be OK at 8 bullets.

;^)
-FR


From: Framers <framers-bounces+docudoc=hotmail@lists.frameusers.com> 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
documentation project because 10 bullets was used. :-).

John X Posada
SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
America Holdings Inc
330 Madison Ave., NY NY

 __





 Phone
  Int: 212-525-5483 Ext: 646-735-1857
 Fax
  Conference Bridge - 877-304-0052, Code 74809254
 Email
  john.x.pos...@us.hsbc.com

 __
 Protect our environment - please only print this if you have to!






From:   "Peter Gold" <knowhow...@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?



___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[Etzel, Gary]

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 example:

- Employing trained, dedicated technical communicators.
- Involving technical documentation from the first day of the project.
- Clearly defining roles, responsibilities, and scope.

And so on.

Gary


-Original Message-
From: Framers 
[mailto:framers-bounces+gary.etzel=dnvgl@lists.frameusers.com] On Behalf Of 
john.x.pos...@us.hsbc.com
Sent: Friday, May 20, 2016 12:49 PM
To: framers@lists.frameusers.com
Subject: [Framers] 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-understood target audience
   Including too little or too much information
   Failure to bring documentation into the project early enough in the
   project
   Failure to establish a governance, review, and approval structure
   Lack of clear  roles and responsibilities
   Belief that “anyone can produce acceptable documentation”
   Lack of feedback early enough in the process to implement without
   wasting a large amount of work and/or affecting deadline
   Scope creep

Anyone want to add more to the list?


John X Posada
SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North 
America Holdings Inc
330 Madison Ave., NY NY

 __





 Phone
  Int: 212-525-5483 Ext: 646-735-1857
 Fax
  Conference Bridge - 877-304-0052, Code 74809254
 Email
  john.x.pos...@us.hsbc.com

 __
 Protect our environment - please only print this if you have to!



-
**
This E-mail is confidential. It may also be legally privileged. If you are not 
the addressee you may not copy, forward, disclose or use any part of it. If you 
have received this message in error, please delete it and all copies from your 
system and notify the sender immediately by return E-mail.

Internet communications cannot be guaranteed to be timely, secure, error or 
virus-free. The sender does not accept liability for any errors or omissions.
**
SAVE PAPER - THINK BEFORE YOU PRINT!
___

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 
http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

**
This e-mail and any attachments thereto may contain confidential information 
and/or information protected by intellectual property rights for the exclusive 
attention of the intended addressees named above. If you have received this 
transmission in error, please immediately notify the sender by return e-mail 
and delete this message and its attachments. Unauthorized use, copying or 
further full or partial distribution of this e-mail or its contents is 
prohibited.
**
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[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 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"
> Mysterious end-customer requirements - an end-customer that can dictate the
> documentation
>
> I speak from experience on documentation failure.
> Catherine
>
> On Fri, May 20, 2016 at 9:48 AM,  wrote:
>
> >
> > 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 information
> >Failure to bring documentation into the project early enough in the
> >project
> >Failure to establish a governance, review, and approval structure
> >Lack of clear  roles and responsibilities
> >Belief that “anyone can produce acceptable documentation”
> >Lack of feedback early enough in the process to implement without
> >wasting a large amount of work and/or affecting deadline
> >Scope creep
> >
> > Anyone want to add more to the list?
> >
> >
> > John X Posada
> > SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
> > America Holdings Inc
> > 330 Madison Ave., NY NY
> >
> >  __
> >
> >
> >
> >
> >
> >  Phone
> >   Int: 212-525-5483 Ext: 646-735-1857
> >  Fax
> >   Conference Bridge - 877-304-0052, Code 74809254
> >  Email
> >   john.x.pos...@us.hsbc.com
> >
> >  __
> >  Protect our environment - please only print this if you have to!
> >
> >
> >
> > -
> > **
> > This E-mail is confidential. It may also be legally privileged. If
> > you are not the addressee you may not copy, forward, disclose or
> > use any part of it. If you have received this message in error,
> > please delete it and all copies from your system and notify the
> > sender immediately by return E-mail.
> >
> > Internet communications cannot be guaranteed to be timely, secure,
> > error or virus-free. The sender does not accept liability for any
> > errors or omissions.
> > **
> > SAVE PAPER - THINK BEFORE YOU PRINT!
> > ___
> >
> > 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
> > http://www.mail-archive.com/framers%40lists.frameusers.com/
> > Subscribe and unsubscribe at
> > http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> > Send administrative questions to listad...@frameusers.com
> ___
>
> 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
> http://www.mail-archive.com/framers%40lists.frameusers.com/
> Subscribe and unsubscribe at
> http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> Send administrative questions to listad...@frameusers.com




-- 

*John Sgammato, Documentation Architect*
*e* john.sgamm...@actifio.com  *c* 508.927.2083
*t* @actifiodocs 

333 Wyman Street, Waltham, MA 02451




*Manage, access, and protect your data with a single platform that saves
you time, money, and complexity.*
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[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"
Mysterious end-customer requirements - an end-customer that can dictate the
documentation

I speak from experience on documentation failure.
Catherine

On Fri, May 20, 2016 at 9:48 AM,  wrote:

>
> 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 information
>Failure to bring documentation into the project early enough in the
>project
>Failure to establish a governance, review, and approval structure
>Lack of clear  roles and responsibilities
>Belief that “anyone can produce acceptable documentation”
>Lack of feedback early enough in the process to implement without
>wasting a large amount of work and/or affecting deadline
>Scope creep
>
> Anyone want to add more to the list?
>
>
> John X Posada
> SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
> America Holdings Inc
> 330 Madison Ave., NY NY
>
>  __
>
>
>
>
>
>  Phone
>   Int: 212-525-5483 Ext: 646-735-1857
>  Fax
>   Conference Bridge - 877-304-0052, Code 74809254
>  Email
>   john.x.pos...@us.hsbc.com
>
>  __
>  Protect our environment - please only print this if you have to!
>
>
>
> -
> **
> This E-mail is confidential. It may also be legally privileged. If
> you are not the addressee you may not copy, forward, disclose or
> use any part of it. If you have received this message in error,
> please delete it and all copies from your system and notify the
> sender immediately by return E-mail.
>
> Internet communications cannot be guaranteed to be timely, secure,
> error or virus-free. The sender does not accept liability for any
> errors or omissions.
> **
> SAVE PAPER - THINK BEFORE YOU PRINT!
> ___
>
> 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
> http://www.mail-archive.com/framers%40lists.frameusers.com/
> Subscribe and unsubscribe at
> http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> Send administrative questions to listad...@frameusers.com
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com

Re: [Framers] What causes documentation to fail

[john . x . posada]

Thanks, Peter...but between you and me, I've never experienced a failed
documentation project because 10 bullets was used. :-).

John X Posada
SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
America Holdings Inc
330 Madison Ave., NY NY

 __ 





 Phone  
  Int: 212-525-5483 Ext: 646-735-1857   
 Fax
  Conference Bridge - 877-304-0052, Code 74809254   
 Email  
  john.x.pos...@us.hsbc.com 

 __ 
 Protect our environment - please only print this if you have to!   






From:   "Peter Gold" <knowhow...@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...@us.hsbc.com> wrote:

  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 information
     Failure to bring documentation into the project early enough in the
     project
     Failure to establish a governance, review, and approval structure
     Lack of clear  roles and responsibilities
     Belief that “anyone can produce acceptable documentation”
     Lack of feedback early enough in the process to implement without
     wasting a large amount of work and/or affecting deadline
     Scope creep

  Anyone want to add more to the list?


  John X Posada
  SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
  America Holdings Inc
  330 Madison Ave., NY NY

   __





   Phone
        Int: 212-525-5483 Ext: 646-735-1857
   Fax
        Conference Bridge - 877-304-0052, Code 74809254
   Email
        john.x.pos...@us.hsbc.com

   __
   Protect our environment - please only print this if you have to!



  -
  **
  This E-mail is confidential. It may also be legally privileged. If
  you are not the addressee you may not copy, forward, disclose or
  use any part of it. If you have received this message in error,
  please delete it and all copies from your system and notify the
  sender immediately by return E-mail.

  Internet communications cannot be guaranteed to be timely, secure,
  error or virus-free. The sender does not accept liability for any
  errors or omissions.
  **
  SAVE PAPER - THINK BEFORE YOU PRINT!
  ___

  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
  http://www.mail-archive.com/framers%40lists.frameusers.com/
  Subscribe and unsubscribe at
  http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
  Send administrative questions to listad...@frameusers.com


** This
message originated from the Internet. Its originator may or may not be who
they claim to be and the information contained in the message and any
attachments may or may not be accurate.
**



-
**
This E-mail is confidential. It may also be legally privileged. If
you are not the addressee you may not copy, forward, disclose or
use any part of it. If you have received this message in error,
please delete it and all copies from your system and notify the
sender immediately by retu

Re: [Framers] What causes documentation to fail

[john . x . posada]

These are the bullets that will be discussed later.

John X Posada
SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
America Holdings Inc
330 Madison Ave., NY NY

 __





 Phone
  Int: 212-525-5483 Ext: 646-735-1857
 Fax
  Conference Bridge - 877-304-0052, Code 74809254
 Email
  john.x.pos...@us.hsbc.com

 __
 Protect our environment - please only print this if you have to!






From:   com/er va ».?
To: john.x.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 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 control that
somewhat by posing some common cases of "doc failure" and showing what went
wrong.
For example:
Symptoms and Causes of Doc Failure
Technical audience does not use doc, thinks it's too "marketing-ish" - Not
writing to a well-understood target audience
Operator audience does not use doc, too much "theory" - Not writing to a
well-understood target audience, Including too much information
Admin audience does not use doc, too "push-button" - Not writing to a
well-understood target audience, Including too little background
information
Doc production cycle is always in crisis mode - Failure to bring
documentation into the project early enough in the project

On Fri, May 20, 2016 at 12:48 PM, <john.x.pos...@us.hsbc.com> wrote:

  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 information
     Failure to bring documentation into the project early enough in the
     project
     Failure to establish a governance, review, and approval structure
     Lack of clear  roles and responsibilities
     Belief that ?anyone can produce acceptable documentation?
     Lack of feedback early enough in the process to implement without
     wasting a large amount of work and/or affecting deadline
     Scope creep

  Anyone want to add more to the list?


  John X Posada
  SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
  America Holdings Inc
  330 Madison Ave., NY NY

   __





   Phone
        Int: 212-525-5483 Ext: 646-735-1857
   Fax
        Conference Bridge - 877-304-0052, Code 74809254
   Email
        john.x.pos...@us.hsbc.com

   __
   Protect our environment - please only print this if you have to!



  -
  **
  This E-mail is confidential. It may also be legally privileged. If
  you are not the addressee you may not copy, forward, disclose or
  use any part of it. If you have received this message in error,
  please delete it and all copies from your system and notify the
  sender immediately by return E-mail.

  Internet communications cannot be guaranteed to be timely, secure,
  error or virus-free. The sender does not accept liability for any
  errors or omissions.
  **
  SAVE PAPER - THINK BEFORE YOU PRINT!
  ___

  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
  http://www.mail-archive.com/framers%40lists.frameusers.com/
  Subscribe and unsubscribe at
  http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
  Send administrative questions to listad...@frameusers.com



--

John Sgammato, Documentation
Architect
e john.sgamm...@actifio.com  c
508.927.2083
t @actifiodocs




 333 Wyman Street, Waltham,
 MA 02451





Manage, access, and protect your data with a single platform that saves you
time, money, and complexity.


** This
message originated from the Internet. Its originator may or may not be who
they claim to be and the inf

Re: [Framers] What causes documentation to fail

[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 control that
somewhat by posing some common cases of "doc failure" and showing what went
wrong.
For example:
*Symptoms and Causes of Doc Failure*
Technical audience does not use doc, thinks it's too "marketing-ish" - Not
writing to a well-understood target audience
Operator audience does not use doc, too much "theory" - Not writing to a
well-understood target audience, Including too much information
Admin audience does not use doc, too "push-button" - Not writing to a
well-understood target audience, Including too little background information
Doc production cycle is always in crisis mode - Failure to bring
documentation into the project early enough in the project

On Fri, May 20, 2016 at 12:48 PM,  wrote:

>
> 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 information
>Failure to bring documentation into the project early enough in the
>project
>Failure to establish a governance, review, and approval structure
>Lack of clear  roles and responsibilities
>Belief that “anyone can produce acceptable documentation”
>Lack of feedback early enough in the process to implement without
>wasting a large amount of work and/or affecting deadline
>Scope creep
>
> Anyone want to add more to the list?
>
>
> John X Posada
> SR AML Syst & Ops Supt Data Analyst | Global Risk Analytics | HSBC North
> America Holdings Inc
> 330 Madison Ave., NY NY
>
>  __
>
>
>
>
>
>  Phone
>   Int: 212-525-5483 Ext: 646-735-1857
>  Fax
>   Conference Bridge - 877-304-0052, Code 74809254
>  Email
>   john.x.pos...@us.hsbc.com
>
>  __
>  Protect our environment - please only print this if you have to!
>
>
>
> -
> **
> This E-mail is confidential. It may also be legally privileged. If
> you are not the addressee you may not copy, forward, disclose or
> use any part of it. If you have received this message in error,
> please delete it and all copies from your system and notify the
> sender immediately by return E-mail.
>
> Internet communications cannot be guaranteed to be timely, secure,
> error or virus-free. The sender does not accept liability for any
> errors or omissions.
> **
> SAVE PAPER - THINK BEFORE YOU PRINT!
> ___
>
> 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
> http://www.mail-archive.com/framers%40lists.frameusers.com/
> Subscribe and unsubscribe at
> http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
> Send administrative questions to listad...@frameusers.com




-- 

*John Sgammato, Documentation Architect*
*e* john.sgamm...@actifio.com  *c* 508.927.2083
*t* @actifiodocs 

333 Wyman Street, Waltham, MA 02451




*Manage, access, and protect your data with a single platform that saves
you time, money, and complexity.*
___

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 http://www.mail-archive.com/framers%40lists.frameusers.com/
Subscribe and unsubscribe at 
http://lists.frameusers.com/listinfo.cgi/framers-frameusers.com
Send administrative questions to listad...@frameusers.com