[Framers] What causes documentation to fail

[john.x.posada at us.hsbc.com]

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.posada at us.hsbc.com

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






From:	com/er va ».?
To:	john.x.posada at us.hsbc.com
Cc:	"framers at lists.frameusers.com" <framers at 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.posada at 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.posada at 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 at 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 listadmin at frameusers.com



--

            John Sgammato, Documentation
            Architect
            e john.sgammato at 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 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!