What are your experiences with version control system usage in technical writing? Tips, tricks...?

[sereshk 146]

Hello Everyone,

I've been using version control in several teams and have got some experience already, mainly git and SVN + TortoiseSVN. 
Setting up a good file and folder structure and make everyone aware of how-tos is an important starting point, to my mind...

We are looking at ways and procedures in our small team to best handle daily collaboration using SVN on software product and feature documentation, including XML-based CCMS.

Especially the merging of conflicts is a rather-to-be-avoided issue. :) As far as possible.

I would like to read about your views and tips or learnings you might want to share here very much, in order to make our current restructuring and planning process a success.

Thanks in advance! Looking forward to any contributions! Highly appreciated!

Kind Regards

Nina

[Robert Lauriston]

Paligo's integrated versioning is very slick. It coordinates versions at the publication and topic level.

A version control system for documentation should support locking topics so only one person can edit at a time. Subversion does. Git doesn't.

Git was designed with no thought for anyone but programmers, who necessarily have to work on shared files at the same time. Tech writers don't.

--
TechWR-L is the “Technical Writers List” — an email discussion list focused on all issues in technical communicatio
---
You received this message because you are subscribed to the Google Groups "TECHWR-L Email Discussion group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to techwr-l+u...@techwr-l.com.
To view this discussion visit https://groups.google.com/a/techwr-l.com/d/msgid/techwr-l/731fdd1e-9af5-45e0-b5f6-f0b78b590df5n%40techwr-l.com.

[Hanson, Paul R]

In a folder of screenshots - saved as PNG files - that can be used in more than one Word files, I want to write alt-text that would be stored in the image (somehow) so that if I insert the image in a Word file, I don't have to add the alt-text to that image and then if I insert the image in a second Word file, I don't have to add the alt-text to that image in the second file. What I'm looking for is a way to add the alt-text once, at the image file level, so that if I insert the image into 10 Word files, I don't have to add the alt-text in each of those 10 Word files. I know the mechanics of adding alt-text to the image after it has been added to the Word file. I want to figure out how to not have to add the alt-text to the same image in multiple Word files at a one Word file at a time basis. I want the alt-text to be carried into the Word file because (somehow) it's already associated with the image.

 

Is it possible to do this if the PNG files is a different graphics file type? For example, if the PNG files were <unknown-to-me-file-extension>, the alt-text could be stored in the image.

 

I know that I can assign alt-text to images in RoboHelp 2022, but we're not using that tool.

 

Thank you for any ideas for how to handle this.

 

Paul Hanson

IT Manager – Disaster Recovery | Technical Support & Implementation | University of Iowa Health Care Information Systems

 

[David Artman]

Tricky ask.

Could you tell us more: 

1) Do you use a file-naming convention? If so, how many characters are used to assemble a file name?

2) Do you use folders to organize graphics; or are they all in one location? 

3) Are all users on the same OS?

4) Does your organization's Group Policies allow macros to run in Office applications? 

I've got an idea or two, but their viability is affected by the answers to the above questions. 

David Artman 

DCA::d.a.d.

--

TechWR-L is the “Technical Writers List” — an email discussion list focused on all issues in technical communicatio
---
You received this message because you are subscribed to the Google Groups "TECHWR-L Email Discussion group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to techwr-l+u...@techwr-l.com.

To view this discussion visit https://groups.google.com/a/techwr-l.com/d/msgid/techwr-l/BYAPR04MB47895709B0C6A25E01BEC82CF5A3A%40BYAPR04MB4789.namprd04.prod.outlook.com.

[Hanson, Paul R]

1. Do you use a file-naming convention? If so, how many characters are used to assemble a file name?

1. One could be adopted as part of a solution – current state is no, there's not a file-naming convention.

1. Do you use folders to organize graphics; or are they all in one location? 

1. This all came up based upon a co-worker asking how to do this for her folder of 18 PNG files in a "Screenshots" folder that are used in 5 different Word files that are distributed as 5 PDF files. Some screenshots are used in more than 1 Word file.

1. Are all users on the same OS?

1. In this scenario, the user guides are for Windows, if that's what you mean?

1. Does your organization's Group Policies allow macros to run in Office applications? 

1. I can run Word macros on my laptop.

 

 

 

Paul Hanson

IT Manager – Disaster Recovery | Technical Support & Implementation

University of Iowa Health Care Information Systems

0405-C28 HSSB | Coralville, IA 52241

 

Useful Links:

Helpde...@uiowa.edu | macdes...@healthcare.uiowa.edu | Customer Feedback?

Change Healthcare Password | Change HawkID Password | HCIS Web Request

Epic Training Resources

 

From: David Artman <da...@davidartman.com>
Sent: Tuesday, December 9, 2025 3:13 PM
To: tech...@techwr-l.com
Subject: [External] Re: [TECHWR-L] - Alt-Text stored at the Image level

 

You don't often get email from da...@davidartman.com. Learn why this is important

To view this discussion visit https://groups.google.com/a/techwr-l.com/d/msgid/techwr-l/196584923522207744.0.v2%40titan.email.

[David Artman]

Ok, it could be easy to implement but manual, or automatic but tricky to implement. 

A) Name your files using the alt text (plus file extension, of course). When you go to insert by reference, when you select the file in the Word dialog, highlight the file name and copy it before clicking OK. Then just paste the file name into the Layout & Properties Alt Text field and backspace the extension and decimal. (You can leave the Layout & Properties pane open in Word to speed up this last step.)

NOTE: Word might even automatically use the file name as default alt text, with some setting or option. I haven't produced in Word in quite some time. But if it does, that saves you the select+copy+paste step; and you'd only have to delete the decimal and extension.

B) Use Windows PNG file properties (ex: the Comments property) to add alt text to the files. Then, use a Visual Basic extension (i.e., a complex macro) instead of the insert-by-reference dialog. That replacement dialog (called by a button on a custom or the Quick Access toolbar) would perform all of the normal insertion actions, but it would ALSO read the Comments Value string and insert it into the Word alt text property of the inserting image at the same time.

Others might have better suggestions; these are what I'd look at....

David Artman 

DCA::d.a.d.

On Tue, Dec 09, 2025, 04:32 PM 'Hanson, Paul R' via TECHWR-L Email Discussion group <tech...@techwr-l.com> wrote:

1. Do you use a file-naming convention? If so, how many characters are used to assemble a file name?
1. One could be adopted as part of a solution – current state is no, there's not a file-naming convention.
2. Do you use folders to organize graphics; or are they all in one location? 
1. This all came up based upon a co-worker asking how to do this for her folder of 18 PNG files in a "Screenshots" folder that are used in 5 different Word files that are distributed as 5 PDF files. Some screenshots are used in more than 1 Word file.
3. Are all users on the same OS?
1. In this scenario, the user guides are for Windows, if that's what you mean?
4. Does your organization's Group Policies allow macros to run in Office applications? 
1. I can run Word macros on my laptop.

 

 

 

Paul Hanson

IT Manager – Disaster Recovery | Technical Support & Implementation

University of Iowa Health Care Information Systems

0405-C28 HSSB | Coralville, IA 52241

 

Useful Links:

Helpde...@uiowa.edu | macdes...@healthcare.uiowa.edu | Customer Feedback?

Change Healthcare Password | Change HawkID Password | HCIS Web Request

Epic Training Resources

 

From: David Artman <da...@davidartman.com>

To view this discussion visit https://groups.google.com/a/techwr-l.com/d/msgid/techwr-l/BYAPR04MB4789898D7A8F9D53C764C845F5A3A%40BYAPR04MB4789.namprd04.prod.outlook.com.

[Stuart Burnfield]

SVG format? Try googling or DuckDuckGoing for: svg alt text

Good luck.

Stuart

--

TechWR-L is the “Technical Writers List” — an email discussion list focused on all issues in technical communicatio
---
You received this message because you are subscribed to the Google Groups "TECHWR-L Email Discussion group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to techwr-l+u...@techwr-l.com.

To view this discussion visit https://groups.google.com/a/techwr-l.com/d/msgid/techwr-l/BYAPR04MB47895709B0C6A25E01BEC82CF5A3A%40BYAPR04MB4789.namprd04.prod.outlook.com.

[Keith Hood]

My experience has been, there isn't a dime's worth of difference between them. Every CMS I've seen since Visual Source Safe has been filled with features that may be useful for software designers, but are irrelevant for technical writers.

You might as well use DropBox. It does everything you need for versioning tech docs. It saves version changes, lets you roll back, gives you controls on file access, and it's free. You don't have to install anything on your own computer, but you can set it up so that you can access your saved files as if the storage locations are folders accessible through File Explorer. 

To view this discussion visit https://groups.google.com/a/techwr-l.com/d/msgid/techwr-l/CAN3Yy4BXHhL5Y1zSGxj4-rW-Y3K9MATbL%2BNWcjk7FkVsrpZg1g%40mail.gmail.com.

[Tony Chung]

Hey Nina. I’m firmly entrenched in the docs-as-code world now but we used to use DITA and the worst part about any VCS was that it did not understand XML to manage differences at the object level rather than as characters in source code. A quick AI assisted Google search  mentioned editors like Oxygen and XMLSpy act as an XML-interpreter for their Git integration. So while Git sees the diffs in the code, the editor’s integration recognizes the differences in the objects.

That might be the way to go, short of a full on CCMS with database and version control.

Regarding merge conflicts, the only solution for that is to merge commits to different files. You don’t need an automated locking system. Just a way to communicate that writer A is working on this block of files and writer 1 on another set. 

Just my two cents.

-Tony 

[sereshk 146]

Hello Keith, hello All,

thanks for the replies. We have a setup as I mentioned that is already in place. I joined recently.

So to me this is no question of changing applications or finding an entirely new way.

Hello @Paul Hanson, even though your question is a little off topic in this thread ;) I wish you the best of luck.

Not using Word for creating documentation I do not face these issues, so cannot provide any help.

Kind Regards

Nina

[em...@armadillosoft.com]

To view this discussion visit https://groups.google.com/a/techwr-l.com/d/msgid/techwr-l/2e953374-79d5-407e-8c20-2592f49f4f6an%40techwr-l.com.

[sereshk 146]

Hello Tony,

thanks for sharing this and thanks for the suggestion.
It's like this, actually: 
We do have a CCMS in place, XML-based, works fine, we are quite content.

Additionally we already are using SVN 'inside' TortoiseSVN.

Currently, in a small team we were wondering, since I joined recently, what experiences or best practices people looking at something similar might care to share.

We did also think of keeping in close contact about who is working on what to avoid merge conflicts as far as possible.

SVN works well since it recognizes the XML-files and the respective code lines fine, and even inside the packaged project configuration files differences are pointed out at every commit.

Thanks again, you confirm what I've also partly found online, that it is mainly about communicating close in time.

Kind Regards

Nina

[Peter Neilson]

Did that by hand 40 years ago. ONE person owned the material to be
changed, and arranged by polite conversation for outside changes that
needed to be integrated into the owner's work.

[Robert Lauriston]

Paligo's integrated versioning is very slick. It coordinates versions
at the publication and topic level.

A version control system for documentation should support locking
topics so only one person can edit at a time. Subversion does. Git
doesn't.

Git was designed with no thought for anyone but programmers, who
necessarily have to work on shared files at the same time. Tech
writers don't.

On Mon, Dec 1, 2025 at 3:48 PM sereshk 146 <seres...@gmail.com> wrote:
>

[Christopher Schmidt]

[sereshk 146]

Hello Robert,

happy new year to you and to all, a little after the event.

I know Paligo, I worked with it for over half a year and also helped to evaluate and test it in another place of work, where migration was the goal. I like it too.

But we have a good CCMS in place that is based on XML-files and we are not thinking of changing that.

Thanks for the suggestion anyway!

I'm sure to look at the locking function of SVN, together with the team.

Kind Regards

Nina