Procedure How to Write a Manual!

[Peter Gold]

On Fri, May 22, 2009 at 8:36 AM, Bodvar Bjorgvinsson <bodvar at gmail.com> wrote:
> I agree that the writer must love the language, but he/she must
> refrain from using "words such as 'transmogrify'" unless there is a
> very good reason for it _and_ you have the word explained in the
> "Terms and Definitions" section. ;-)
> Have KISS in mind - as much as practicable, when writing technical manuals.
>
> Regarding the "endianess", I had a problem some 13 years ago with some
> UNIX software that was supposed to work on Linux. It did not. I sent a
> query to an Icelandic guy on the "Basic Linux Training" list I
> subscribed to and he came up with a solution. Then he expained to me
> that there was a difference between Linux an UNIX that one used big
> endian and the other little endian in the same code of software. The
> first time I saw the term(s) I thought this must be a misspelling,
> knowing that programmers often have weird kind of humor. What would it
> be they referred to as Indians?
>
> To this day I have not had any explanation understandable to me what
> the real difference is. Neither have i had any problems with little or
> big endians (or any sort of Indians) since. ;-)
>
> Bodvar
I also ran into "endian" while documenting a UNIX application. A
subject-matter expert (SME) patiently explained it to me, though my
impression at the time was that he was a little uncertain. Perhaps the
uncertainty was about the explanation itself, not about his grasp of
the concept.

His explanation was simply that some processor chips interpret binary
code (ones and zeroes) from the "Big end" and others "Little end." So
a binary number that appears like 1000 to one chip would appear as
0001 to the other. I forget whether the big end is on the left or the
right.

While it made enough sense to me to move on with my project, the whole
endianness issue came up in the first place because he introduced it
in explaining communication protocols. I was trying to understand why
an illustration of two protocols communicating between computers
didn't seem correct. It used two parallel lines; one for TCP/IP, and
the other for another protocol. I was supposed to add a third protocol
to the illustration, but a third parallel line didn't /quite seem
proper.

After a bunch of interviews with different SMEs, I was able to dig out
the key: a particular  protocol is indicated by code that precedes a
packet of information, and usually also is appended to the packet. The
codes identify the protocol, so the packet contents are processed
correctly. All the packets move on the same network channel; each
protocol is identified by different code around the packets. I
corrected the illustration to indicate one communication line between
the computers; sets of identifiers, like "xpacketx ypackety zpacketz,"
indicated the x, y, and z protocols moving along the single line.

In addition, if you haven't already, search Google for endian.

Regards,

Peter
__________________
Peter Gold
KnowHow ProServices