Re: [Framers] Fwd: Managing Versions of documentation simultaneously

[Robert Lauriston]

To my knowledge, there's no practical way to do that kind of parallel
updating of doc versions using unstructured FrameMaker.

If updating multiple versions of the doc is a requirement, you should
evaluate other tools with better support for reuse, versioning,
variable sets, and profiling. Paligo works great for me and is
reasonably priced, but there are other alternatives, including
Author-it, Flare plus MadCap Central, and structured FrameMaker with
DITAToo or some other compatible CMS.

Switching from unstructured to structured FrameMaker could be a lot
more work than switching to Flare, which can directly import
FrameMaker files, or Paligo, which can import XHTML exported from
FrameMaker.

On Wed, May 2, 2018 at 10:06 PM, Caroline Tabach
 wrote:
> So is Paligo instead of FrameMaker?
>
> Caroline Tabach
>
> בתאריך יום ד׳, 2 במאי 2018, 23:41, מאת Robert Lauriston ‏<
> rob...@lauriston.com>:
>
>> The way I have things set up on Paligo, when we ship, say, release
>> 1.2, I branch the 1.2 doc to create the 1.3 doc, and  update the
>> version number variable in the 1.3 doc to reflect the new number.
>>
>> At that point, all the topics are the same. If I generate the 1.3 doc,
>> it's identical to the 1.2 doc except that all of the version number
>> references say 1.3.
>>
>> For a  new feature, I add a topic to 1.3, and it appears only in that doc.
>>
>> When I have a correction to a topic that applies to both 1.2 and 1.3,
>> I make the change in either one, and both docs are updated.
>>
>> When I have a change that applies only to 1.3, I branch the topic and
>> make the change in the 1.3 version.
>>
>> When I have a change that applies to both branches of a branched topic
>> (fairly rare), I can make the change in one and reuse the relevant
>> paragraph(s) in the other. Sometimes the paragraphs are already reused
>> so I just make the change in one place.
>>
>> This approach greatly reduces the amount of work required to maintain
>> docs for multiple releases. It also reduces the likelihood of errors.
___

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] Fwd: Managing Versions of documentation simultaneously

[Caroline Tabach]

So is Paligo instead of FrameMaker?

Caroline Tabach

בתאריך יום ד׳, 2 במאי 2018, 23:41, מאת Robert Lauriston ‏<
rob...@lauriston.com>:

> The way I have things set up on Paligo, when we ship, say, release
> 1.2, I branch the 1.2 doc to create the 1.3 doc, and  update the
> version number variable in the 1.3 doc to reflect the new number.
>
> At that point, all the topics are the same. If I generate the 1.3 doc,
> it's identical to the 1.2 doc except that all of the version number
> references say 1.3.
>
> For a  new feature, I add a topic to 1.3, and it appears only in that doc.
>
> When I have a correction to a topic that applies to both 1.2 and 1.3,
> I make the change in either one, and both docs are updated.
>
> When I have a change that applies only to 1.3, I branch the topic and
> make the change in the 1.3 version.
>
> When I have a change that applies to both branches of a branched topic
> (fairly rare), I can make the change in one and reuse the relevant
> paragraph(s) in the other. Sometimes the paragraphs are already reused
> so I just make the change in one place.
>
> This approach greatly reduces the amount of work required to maintain
> docs for multiple releases. It also reduces the likelihood of errors.
> ___
>
> 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] Fwd: Managing Versions of documentation simultaneously

[Robert Lauriston]

The way I have things set up on Paligo, when we ship, say, release
1.2, I branch the 1.2 doc to create the 1.3 doc, and  update the
version number variable in the 1.3 doc to reflect the new number.

At that point, all the topics are the same. If I generate the 1.3 doc,
it's identical to the 1.2 doc except that all of the version number
references say 1.3.

For a  new feature, I add a topic to 1.3, and it appears only in that doc.

When I have a correction to a topic that applies to both 1.2 and 1.3,
I make the change in either one, and both docs are updated.

When I have a change that applies only to 1.3, I branch the topic and
make the change in the 1.3 version.

When I have a change that applies to both branches of a branched topic
(fairly rare), I can make the change in one and reuse the relevant
paragraph(s) in the other. Sometimes the paragraphs are already reused
so I just make the change in one place.

This approach greatly reduces the amount of work required to maintain
docs for multiple releases. It also reduces the likelihood of errors.
___

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] Fwd: Managing Versions of documentation simultaneously

[Fred Wersan]

Well, you could think of it like what is done with version control. When 
Release 3 of Application A comes out, they create a branch for Release 3 
and the trunk continues forward to Release 3.1 or 4 or whatever. 
Sometimes fixes for Release 3 are that release only. Sometimes they also 
go into the trunk. You can always build that Release 3 again from the 
branch.


When your manual is frozen for Release 3, make a copy of it. Keep your 
main source for moving forward for the next release. If you need to 
change something in the release 3 doc, you just change it there. If it 
also applies to next release, put it in your source.


Will you end up with several branches over time? Yes. The question is - 
how active are these older branches. Probably not as active as the 
trunk. You don't have to worry about different versions polluting each 
other.


At some point each of the approaches has a certain amount of overhead - 
maintaining somewhat similar duplicate files, maintaining sensible 
conditions, structured or unstructured, etc. So pick the method that 
best fits your tool set and your overall doc management flow.


Fred

--

*Fred Wersan* | Principal Technical Writer
*VT MAK* | 150 Cambridge Park Drive, Third Floor, Cambridge, MA 02140
T: +1.857.209.3469 | F: +1.617.876.0032
fwer...@mak.com | www.mak.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] Fwd: Managing Versions of documentation simultaneously

[Robert Lauriston]

The nature of software releases means that the number of conditions
would grow indefinitely. I don't see how this would not eventually
become unmanageable.

DITA (which is just a text markup standard) doesn't make sense if you
don't have a lot more reuse than simply maintaining multiple versions
of a doc. Typically it's cost-effective in large organizations where
multiple products share features (and thus can reuse content in their
docs) and the docs are translated into multiple languages, and in that
context it defines the format for files that are managed by a
compatible CMS, which is integrated with an editor such as Oxygen and
often custom code for generating PDF, online help, static HTML for web
sites, etc.

For a small or medium-sized company, DITA's almost certainly the wrong
choice. Paligo and I believe Author-it provide integrated systems with
similar features. Flare with MadCap Central may also be a practical
and cost-effective alternative.

On Wed, May 2, 2018 at 10:16 AM, Keith Soltys  wrote:
> I think it would depend on how many simultaneous versions you have to
> manage. I've done something similar in Frame where I had to keep three
> different versions of a document from one set of source files - there were
> different features for different roles, not versions per se, but the
> problem was the same. I did it with conditions - the tricky part was where
> I had overlapping information; for example, something applies to A and B
> but not C and something else applies to B and C but not A. If memory
> serves, I ended up with 14 separate conditionals because I also had
> separate print an online formats to manage. It was doable, but very
> finicky, and I wouldn't do it again if there were more than three major
> variants. (This was before Frame came out with conditional expressions,
> which might have simplified things a little, but it would still be
> finicky).
>
> I have not used it, but I have been told that DITA is a better solution
> here; but I couldn't say whether structured Frame or something like Oxygen
> with a back-end CMS would be better.
___

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] Fwd: Managing Versions of documentation simultaneously

[Keith Soltys]

I think it would depend on how many simultaneous versions you have to
manage. I've done something similar in Frame where I had to keep three
different versions of a document from one set of source files - there were
different features for different roles, not versions per se, but the
problem was the same. I did it with conditions - the tricky part was where
I had overlapping information; for example, something applies to A and B
but not C and something else applies to B and C but not A. If memory
serves, I ended up with 14 separate conditionals because I also had
separate print an online formats to manage. It was doable, but very
finicky, and I wouldn't do it again if there were more than three major
variants. (This was before Frame came out with conditional expressions,
which might have simplified things a little, but it would still be
finicky).

I have not used it, but I have been told that DITA is a better solution
here; but I couldn't say whether structured Frame or something like Oxygen
with a back-end CMS would be better.

Regards
Keith

--
Keith Soltys
Senior Technical Writer
Architecture / Global Technology Services

T +1 416 947-4397


TMX | www.tmx.com 


On Wed, May 2, 2018 at 12:54 PM, Robert Lauriston 
wrote:

> I switched to Paligo in part because it's very good at maintaining
> multiple versions and handling reuse across versions. It has an
> integrated CMS that handles that stuff.
>
> I presume that structured FrameMaker with a compatible CMS that
> supports reuse can do what I do with Paligo, but switching from
> structured to unstructured might be more work than migrating to
> Paligo, Author-it, or some other integrated system.
>
> Trying to do that with conditional text in unstructured FrameMaker
> would be a nightmare. What happens in a few years when you've
> accumulated five or ten versions?
>
> On Tue, May 1, 2018 at 10:52 PM, Caroline Tabach
>  wrote:
> > I have been asked what SW writing tool can manage versions.
> >
> > At first I thought "version control" like you have in Software, but I
> found
> > they meant maintaining multiple versions of the User guides at the same
> > time.
> >
> > For instance, even when SW version 4 is released we will still have to
> > update and maintain SW version 3, as features are added and developed.
> >
> > Some things in these versions are totally different, and some are the
> same
> > and need to be updated in the same way in both guides.
> >
> > I was asked if there is a magic writing tool that does this.
> >
> > I think we could use conditional text in FrameMaker to do this, but in
> the
> > end it is the writer who must set it up and manage it.
> >
> > Do other people encounter this scenario?
> > What do you do?
> ___
>
> 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
>

-- 

NOTICE OF CONFIDENTIALITYThis e-mail, including all materials contained in 
or attached to this e-mail, contains proprietary and confidential 
information solely for the internal use of the intended recipient. If you 
have received this email in error, please notify us immediately by return 
e-mail or otherwise and ensure that it is permanently deleted from your 
systems, and do not print, copy, distribute or read its contents.
AVIS DE 
CONFIDENTIALITÉLe présent courriel, y compris tous les documents qu'il 
contient ou qui y sont joints, renferme des renseignements exclusifs et 
confidentiels destinés uniquement à l'usage interne du destinataire prévu. 
Si vous avez reçu le présent courriel par erreur, veuillez nous aviser 
immédiatement, notamment par retour de courriel, et vous assurer qu'il est 
supprimé de façon permanente de vos systèmes; veuillez également vous 
abstenir d'imprimer, de copier, de distribuer ou de lire son contenu.
___

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] Fwd: Managing Versions of documentation simultaneously

[Robert Lauriston]

I switched to Paligo in part because it's very good at maintaining
multiple versions and handling reuse across versions. It has an
integrated CMS that handles that stuff.

I presume that structured FrameMaker with a compatible CMS that
supports reuse can do what I do with Paligo, but switching from
structured to unstructured might be more work than migrating to
Paligo, Author-it, or some other integrated system.

Trying to do that with conditional text in unstructured FrameMaker
would be a nightmare. What happens in a few years when you've
accumulated five or ten versions?

On Tue, May 1, 2018 at 10:52 PM, Caroline Tabach
 wrote:
> I have been asked what SW writing tool can manage versions.
>
> At first I thought "version control" like you have in Software, but I found
> they meant maintaining multiple versions of the User guides at the same
> time.
>
> For instance, even when SW version 4 is released we will still have to
> update and maintain SW version 3, as features are added and developed.
>
> Some things in these versions are totally different, and some are the same
> and need to be updated in the same way in both guides.
>
> I was asked if there is a magic writing tool that does this.
>
> I think we could use conditional text in FrameMaker to do this, but in the
> end it is the writer who must set it up and manage it.
>
> Do other people encounter this scenario?
> What do you do?
___

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] Fwd: Managing Versions of documentation simultaneously

[Carol J. Elkins]

At 11:52 PM 5/1/2018, Caroline Tabach wrote:
I have been asked what SW writing tool can manage versions. At first 
I thought "version control" like you have in Software, but I found 
they meant maintaining multiple versions of the User guides at the 
same time. For instance, even when SW version 4 is released we will 
still have to update and maintain SW version 3, as features are 
added and developed. Some things in these versions are totally 
different, and some are the same and need to be updated in the same 
way in both guides



I house multiple versions of a document in a Framemaker folder and 
build the version number into the filename. However, I personally do 
not single-source the content of these files.


You might consider making one of the versions the "source" file and 
then create the content of the other versions by using individual 
cross-references to paragraphs in the source file. That keeps the 
single-sourced content current with the "source" file and allows you 
to create non-cross-referenced paragraphs for unique content.


This approach will not work well if you have a lot of 
cross-references in your source file's paragraphs, because 
cross-references within text insets are problematic. But I believe 
you can build a workaround for this using an Extendscript. But I have 
no experience with that.


Carol



___

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] Fwd: Managing Versions of documentation simultaneously

[Lin Sims]

You can use conditional text to do this, but you have to be very careful
with tagging the conditional text. I've done this with a very, very
complicated documentation set: 3 main platforms with between 2-4 versions
each, with internal and external conditions on top of that.

There are two ways to approach this:

One is to have only one condition applied to any text. This has the
disadvantage of requiring duplication of text if you have identical text
in, say, two versions of the document but not in a third, and you also have
to have a separate condition for each possible output. It has the advantage
that you only have to turn on one condition to see a particular document,
which simplifies creating output enormously.

The other is to layer conditions on text that appears in multiple versions
of the document. This has the advantage of having the text in the document
only once, which cuts down on updating that information for multiple
versions of a document. It has the disadvantage of requiring the use of
Frame's conditional expression builder, and this can get hairy depending on
the number of conditions and outputs you have. I've done this (see above),
but it took me a while to work out how.

At some point, I'll have to finish my write-up of how to create conditional
expressions, since Frame's documentation on this is minimal. I got a LOT of
help from this list, though, so if I have time over the next couple of
nights I'll try to finish that write up and share it with people.

On Wed, May 2, 2018 at 1:52 AM, Caroline Tabach 
wrote:

> Caroline Tabach
>
> -- Forwarded message -
> From: Caroline Tabach 
> ‪Date: יום ג׳, 1 במאי 2018, 16:23‬
> Subject: Managing Versions of documentation simultaneously
> To: techsho...@yahoogroups.com 
>
>
> Hi
>
> I have been asked what SW writing tool can manage versions.
>
> At first I thought "version control" like you have in Software, but I found
> they meant maintaining multiple versions of the User guides at the same
> time.
>
> For instance, even when SW version 4 is released we will still have to
> update and maintain SW version 3, as features are added and developed.
>
> Some things in these versions are totally different, and some are the same
> and need to be updated in the same way in both guides.
>
> I was asked if there is a magic writing tool that does this.
>
> I think we could use conditional text in FrameMaker to do this, but in the
> end it is the writer who must set it up and manage it.
>
> Do other people encounter this scenario?
> What do you do?
>
> Any input or ideas?
>
> thanks
>
> --
> Caroline Tabach
> Technical/Marcom Writer
> e-mail: caroline.tab...@gmail.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




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

[Framers] Fwd: Managing Versions of documentation simultaneously

[Caroline Tabach]

Caroline Tabach

-- Forwarded message -
From: Caroline Tabach 
‪Date: יום ג׳, 1 במאי 2018, 16:23‬
Subject: Managing Versions of documentation simultaneously
To: techsho...@yahoogroups.com 


Hi

I have been asked what SW writing tool can manage versions.

At first I thought "version control" like you have in Software, but I found
they meant maintaining multiple versions of the User guides at the same
time.

For instance, even when SW version 4 is released we will still have to
update and maintain SW version 3, as features are added and developed.

Some things in these versions are totally different, and some are the same
and need to be updated in the same way in both guides.

I was asked if there is a magic writing tool that does this.

I think we could use conditional text in FrameMaker to do this, but in the
end it is the writer who must set it up and manage it.

Do other people encounter this scenario?
What do you do?

Any input or ideas?

thanks

-- 
Caroline Tabach
Technical/Marcom Writer
e-mail: caroline.tab...@gmail.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