New to single sourcing
-
Bambina_Mena
- Propeller Head
- Posts: 39
- Joined: Tue Jul 23, 2013 4:42 pm
New to single sourcing
I'm scheduled for a Flare webinar on single sourcing. I've a document (installation guide) that goes through repeated updates for various versions. I'm jumping through hoops to keep up manually. For example, I've a 5.03 service pack 8 version; a 5.1 SP3 version. Keeping up with the service packs does not allow me much time to make a major update - no service pack but feature/enhancements, etc. instead for, example, a 5.2 major release. It occurred to me that single-sourcing may be the way to go. I currently use Flare for online help systems. In the install guide case, I'd be taking it into Flare and working from there. Any input, thoughts, past experiences, etc. would be greatly appreciated. Thanks!
Re: New to single sourcing
I'm in the act of single sourcing my Installation Guide too, which has been a mega-nightmare to maintain in multiple versions (and also multiple product brandings) manually. I thought a lot about it before I started, so offer the following pointers which worked for me. To decide what is going to work for you, I suggest you analyse what is common/different about each of your variants then try a few typical topics before you do the whole thing.
My overall advice is to keep it as simple as possible. Don't go to town on convoluted conditionals if you can avoid it, as this will rapidly grow into a maintenance headache.
I try to avoid snippet conditions where possible (where you put conditional content in a snippet, then define at the topic level what conditional to apply). Reason - I don't think MadCap has made a sufficient distinction between snippet conditions and "ordinary conditions", and it's quite possible that one will override the other when the target is built, if you're not really careful, especially several builds down the line when someone else is working on one of your convoluted topics and mixes up a snippet condition and an ordinary condition. Now, if snippet conditions were completely separate from ordinary conditions, and were applied at the point where the snippet was placed in a topic, and could not ever be set again at the target level or changed at the topic level (so nothing could override anything else when the target was built), I'd feel very differently, and they would be very useful indeed.
Comments - use comments copiously. I have defined a special "Comment" conditional tag which is always excluded from outputs, that I use that at the start of any snippet or common topic in my install guide. Just like code comments, it explains the circumstances where the snippet or common topic can be used, and in necessary, any warnings about its use. It also serves to remind you much later on why you did what you did.
Folder structure - it's worth spending a bit of time thinking this through. I have a separate folder for common topics, and also separate folders for topics specific to each scenario. I do the same for snippets. This means that I can find things easily and see exactly what I have got.
I tend to have two approaches to single-sourcing, depending on the content and applicability. Again, what I'm aiming for is to keep it simple and maintainable. I aim to make anything that is shared in many places as simple as possible, conditional-free, and commented. (Did I say I have a specific conditional tag for comments?
)
My first option is to conditionalise with a common topic. I will include some "comment" text at the beginning, explaining that this is a common topic (so I recognise it as such when I come across it six months later and don't try to apply edits that don't apply to all placements), and, if necessary, the circumstances to in which it applies. But I will not use a common topic if I need to apply lots of conditionals for different installation variants in the topic, because I think that is making it more complicated, less generally useful and far less maintainable and extensible. In that case, I will opt for the second option.
My second option is to conditionalise with snippets. I do this at the highest level at which the snippet doesn't need conditionals to work. Again, I "comment" the snippet, explaining what it does and where it applies, and what you need to wrap round it to make it work in the document. Then, I will have specific topics for each of my scenarios, which have text in the topic that applies specifically to that scenario, and which calls the snippet to do the discrete task i wrote the snippet for.
Example of snippet use. I have different instructions for preparing for an upgrade depending on which version you are upgrading from. If you upgrade from version 1, you will need to upgrade your SQL Server version first. If you upgrade from version 2, you won't. But in both cases you need to configure new database access permissions. Also, you may have a single server installation, or you may have a dual server installation, in which case you have two servers to upgrade, not just one. So I have a single snippet for upgrading SQL server and a single snippet for configuring the new database access permissions. I may (or may not) include those snippets in multiple topics. So in my document structure (which has separate chapters for single server upgrades and dual server upgrades):
Good luck!
My overall advice is to keep it as simple as possible. Don't go to town on convoluted conditionals if you can avoid it, as this will rapidly grow into a maintenance headache.
I try to avoid snippet conditions where possible (where you put conditional content in a snippet, then define at the topic level what conditional to apply). Reason - I don't think MadCap has made a sufficient distinction between snippet conditions and "ordinary conditions", and it's quite possible that one will override the other when the target is built, if you're not really careful, especially several builds down the line when someone else is working on one of your convoluted topics and mixes up a snippet condition and an ordinary condition. Now, if snippet conditions were completely separate from ordinary conditions, and were applied at the point where the snippet was placed in a topic, and could not ever be set again at the target level or changed at the topic level (so nothing could override anything else when the target was built), I'd feel very differently, and they would be very useful indeed.
Comments - use comments copiously. I have defined a special "Comment" conditional tag which is always excluded from outputs, that I use that at the start of any snippet or common topic in my install guide. Just like code comments, it explains the circumstances where the snippet or common topic can be used, and in necessary, any warnings about its use. It also serves to remind you much later on why you did what you did.
Folder structure - it's worth spending a bit of time thinking this through. I have a separate folder for common topics, and also separate folders for topics specific to each scenario. I do the same for snippets. This means that I can find things easily and see exactly what I have got.
I tend to have two approaches to single-sourcing, depending on the content and applicability. Again, what I'm aiming for is to keep it simple and maintainable. I aim to make anything that is shared in many places as simple as possible, conditional-free, and commented. (Did I say I have a specific conditional tag for comments?
)My first option is to conditionalise with a common topic. I will include some "comment" text at the beginning, explaining that this is a common topic (so I recognise it as such when I come across it six months later and don't try to apply edits that don't apply to all placements), and, if necessary, the circumstances to in which it applies. But I will not use a common topic if I need to apply lots of conditionals for different installation variants in the topic, because I think that is making it more complicated, less generally useful and far less maintainable and extensible. In that case, I will opt for the second option.
My second option is to conditionalise with snippets. I do this at the highest level at which the snippet doesn't need conditionals to work. Again, I "comment" the snippet, explaining what it does and where it applies, and what you need to wrap round it to make it work in the document. Then, I will have specific topics for each of my scenarios, which have text in the topic that applies specifically to that scenario, and which calls the snippet to do the discrete task i wrote the snippet for.
Example of snippet use. I have different instructions for preparing for an upgrade depending on which version you are upgrading from. If you upgrade from version 1, you will need to upgrade your SQL Server version first. If you upgrade from version 2, you won't. But in both cases you need to configure new database access permissions. Also, you may have a single server installation, or you may have a dual server installation, in which case you have two servers to upgrade, not just one. So I have a single snippet for upgrading SQL server and a single snippet for configuring the new database access permissions. I may (or may not) include those snippets in multiple topics. So in my document structure (which has separate chapters for single server upgrades and dual server upgrades):
- The topic for upgrading a single server installation will say "If you are upgrading from Version 1, you must first upgrade SQL Server. To do this: <my SLQ Server upgrade snippet goes here>"
- The topic for upgrading a dual server installation will say "If you are upgrading from Version 1, you must first upgrade SQL Server. To do this, on the Side A server: <my SLQ Server upgrade snippet goes here>. Repeat these steps on the Side B server."
- Both the above topics will include the snippet to configure the new database access permissions, with suitable introductory text. Neither will make reference to the version you are upgrading from, as it doesn't matter, but the dual server topic will tell you to do it first on the Side A server, then the Side B server.
Good luck!
Marjorie
My goal in life is to be as good a person as my dogs already think I am.
My goal in life is to be as good a person as my dogs already think I am.
-
vola_newbie2
- Propeller Head
- Posts: 10
- Joined: Fri Jul 12, 2013 4:53 am
Re: New to single sourcing
Thanks Marjorie for sharing your experience of single-sourcing.
Your explanations are precious!
Your explanations are precious!