[FM Discuss] Editions [was : ISBN Numbers Summary]

[Janet Swisher]

On Mon, Mar 30, 2009 at 6:12 PM, Anne Gentle
<annegentle at justwriteclick.com> wrote:
> Thing is, with manuals, there are no editions. Sometimes software gets
> updated too often for the writers to keep up, even paid ones in an
> enterprise situation. In that case, Release notes and Patch doc of
> some sort are sufficient.

> This 0.84 release
> is quite substantial and a break-off point though, so it's important
> to do a full book update. 0.86 may be the same way but we'll make that
> call when we come to it.

The main reason for a new ISBN would be if you want to be able to sell
both manuals simultaneously through retailers like Amazon. Retailers
are accustomed to selling only one "edition" of a book at a time. When
the 2nd edition comes out, they stop selling the first edition. So it
would be better to consider them different books, in that case.

> Editions aren't the right term for "manuals" in the enterprise
> environment either.

When I was at Motorola, there were just "revisions" of documents.
Revision numbers started at 0 and incremented as much as necessary
(integers, not decimals). The primary model in that environment was
manuals for chips, so there weren't usually different "releases" in
the software sense, just different stages in product development. Some
customers could get documentation at very early stages, long before
the "final" product release. Sometimes the manual got a new revision
as more information became available from engineering, even though the
product was still in the same development stage.

> I also wonder what do Emma Jane or Janet say about open source
> manuals? Does Drupal or Open Office get a new "manual" each release,
> or just release notes?

For the OOoAuthors books, there are different manuals for 1.x vs. 2.x
vs. 3.x.  Each subsequent version is based on the previous version,
but is considered a new manual. For major releases, it's possible to
get started on the new book by working from beta releases. But for
minor releases, the manuals are just updated, usually lagging behind
the software releases.

> Now, to offer another viewpoint on books, I've run into a separate
> "book" request at work before, and in a consulting request - the
> company wants a 3rd party book from a publisher for a product.

> For example, writing a "3rd party book" (there's probably a better
> term but I'm not sure what it is) about Sugar (like a teachers
> workbook) would be a very different thing than a manual for Sugar. But
> you may save time/effort by remixing in chapters from the Sugar Users
> Guide.
>
> So I guess I would say FLOSS Manuals is at this interesting junction
> where we provide classic manuals but also provide something like "3rd
> party" books. It's a neat junction to be at, but there are different
> expectations for a manual than a "3rd party" book. That's my take of
> the situation. I'd love to hear from others' experiences as well.
>
> Anne