Re: Documentation Architect vs. Technical Expert !

["Mark Baker" <listsub -at- analecta -dot- com>]

John Posada wrote:

> >I needed my technical knowledge to match that
> >of my audience...
>
> Mark...if you only know as much as your readers already know, what
> benefit do they get from the documents...they already know it.

I needed to know what an experienced OmniMark programmer knows in order to
communicate to a novice what an experienced OmniMark programmer needs to
know.

I needed to know what an experienced OmniMark Programmer knows in order to
communicate to an experienced OmniMark Programmer about new features in the
product and how they would impact his work.

I needed to know what an experienced OmniMark programmer knows in order to
write reference material that will be meaningful and useful to an
experienced OmniMark programmer when he looks up a function that he does not
use very often and has not committed to memory.

> >I did not need to know what the developers
> >knew: how to build a compiler, how to architect
> >a streaming parser, or how to write portable
> >C code.
>
> This is not what the developers know about that the customer cares
> about, just as you knowing how to build a TOC is not what the customer
> cares about. What the developer does know is what a specific piece of
> "portable C code" does with data, that is important to the customer.
> Then maybe if you also had that knowledge of how that piece of "portable
> C code" works, you could enlighten the customer on using the application
> containing that piece of code to do whatever it is that they do, better.

But you don't have to understand how to code function in portable C code in
order to understand the way in which that function manipulates data. In
fact, if doesn't even matter if the function is written in portable C or in
Java or C#. What matters is its functional properties, not its
implementation. This is called encapsulation. Encapsulation is your friend.
It enables you to spend less time worrying about how the product is built
and more about how it is used. In the end, your ability to deliver the
greatest value to the reader is determined by how well you understand their
needs. That's where you need to focus as much of your attention as possible.

---
Mark Baker
Analecta Communications
+1 613 614 5881