Best way to import updates into tagged H&M project?

[Anja Smidt Nielsen]

What is the best way to handle updates to a H&M project with many build tags (for 4 different output versions), i.e. is it possible to re-import a document with updated input (from Word/RTF) without losing the existing tags in the project?

[Tim Green]

Hi Anja,

What is the best way to handle updates to a H&M project with many build tags (for 4 different output versions), i.e. is it possible to re-import a document with updated input (from Word/RTF) without losing the existing tags in the project?

No, "round-tripping" like this isn't supported in Help+Manual. Don't try to export to other programs, edit there and then re-import. That will simply create a huge amount of unnecessary extra work, because by definition those formats can't contain things like build tags, toggles and much more besides. Importing is only there to get outside data into Help+Manual. After that, any further editing should be performed inside the program.

[Anja Smidt Nielsen]

Thanks for the quick response, Tim. Which procedure will you then recommend for us. For a lot of our manuals we (Technical Writers) get all input from the developers. We import it into H&M for the first version of the manual, style it, tag it and publish it. Then we output a version in PDF or Word for the developers to do future updates in, which they then return to us with updates for the next release. What would be the best way to get these updates into a tagged H&M project?

[Simon_Dismore]

we output a version in PDF or Word for the developers to do future updates in, which they then return to us with updates for the next release. What would be the best way to get these updates into a tagged H&M project?

[Excuse me interrupting], I'd like to have a cut-down version of H&M that contributors could use for updates. I suggest using the Pro version – i.e. allowing hxmp files and source control – with three main restrictions:

• No manual formatting (only existing styles can be used)
• No access to project configuration, XML source or Topic Options
• No ability to publish

There was some discussion on this thread a couple of years ago.

[Tim Green]

Then we output a version in PDF or Word for the developers to do future updates in, which they then return to us with updates for the next release. What would be the best way to get these updates into a tagged H&M project?

You can import Word files into an existing project with Import in the File menu, by saving the files to RTF first in Word. So long as they use the standard Word Heading 1 ... Heading 6 styles for the sections (which you will need to change after exporting) you will get a topic and chapter structure when you import, and the styles that have the same names will match. But it will be new chapters and topics, so you will need to copy and paste to the original topics after importing. Any build tags and other HM structures and features were gone as soon as you exported to Word, so they won't come back in -- you can't import what isn't there. As I indicated, this is really a lot of work if you try to "round trip" via Word like this, as it isn't supported.

With PDF, not at all, unfortunately. You can use PDF for commenting only. You can export your comments from Help+Manual to PDF for review, but you cannot import anything from PDF. It's important to understand that PDF isn't a document format; it is really just raw printer data in a file, displayed on the screen with a special printer driver. There is nothing in it that could be imported, apart from plain text, and so HM doesn't import PDF at all, neither its own PDFs nor others.

I'd like to have a cut-down version of H&M that contributors could use for updates.

This is something we've discussed but it isn't really practical. You will then still have multiple copies of the project edited by different people and then how do you want to merge all the different versions? The only really efficient way to handle this is to store a copy of your project in a Subversion (SVN) or Team Foundation Server (TFS) version control system, which is actively supported by Help & Manual Pro and Server editions. Then each user works on a linked copy of the project on their own computers, which they synchronize via the SVN or TFS server. This provides all the advantages of direct remote editing, but each author is still working on their own local (but linked) copy rather than directly via an Internet connection.

Note that the remote authors will need their own copies of Help & Manual Professional on their own computers to do this, because the server version is for LAN only. Alternatively they could be using the server version on the LAN in their own office but working on a shared SVN project with that.

If you have not already deployed TFS in your company we strongly recommend using SVN rather than TFS. SVN is more flexible, easier to manage and configure and interfaces better with tools like Help & Manual. It is an open-source system and all the components you need for it are completely free.

Working with a version control system gives you the advantage that your remote authors can work on their projects offline. They only need to connect to the copy on your server to synchronize their work with the master copy. Before starting work they open the project and select "Synchronize SVN/TFS" in the Help & Manual toolbar to update their local copy with any new changes that other authors have made in the meantime. Then when they have finished their session they select Synchronize SVN/TFS again to merge their own changes with your master copy.

This works even if two people have worked on the same topics. If they have edited different parts of the topics the changes are just merged silently, because there are no conflicts. If they have both edited the same text you get a dialog asking you which versions of each change you want to keep ("mine" or "theirs"). Agreements between team members on which topics to work on can keep these conflicts to a minimum.

Once you have stored your project in your version control repository, which can also be made available online, each author downloads a local working copy of the project from the repository. This working copy is what they edit, but it remains linked to the "master" copy in the repository. Only changes need to be transferred in either direction, which means that once each author has their own local copy of the project only very small amounts of data need to be transferred when they synchronize their work with the master copy. This makes the solution extremely efficient and also very robust -- you have none of the data integrity and speed nightmares involved in live editing via an open connection.

For information on setting up and using Help & Manual with version control systems please see this chapter in the HM help:

https://www.helpandmanual.com/help/inde ... ed_vcs.htm

[Simon_Dismore]

I'd like to have a cut-down version of H&M that contributors could use for updates.

This is something we've discussed but it isn't really practical. You will then still have multiple copies of the project edited by different people and then how do you want to merge all the different versions? The only really efficient way to handle this is to store a copy of your project in a Subversion (SVN) or Team Foundation Server (TFS) version control system, which is actively supported by Help & Manual Pro and Server editions. Then each user works on a linked copy of the project on their own computers, which they synchronize via the SVN or TFS server. This provides all the advantages of direct remote editing, but each author is still working on their own local (but linked) copy rather than directly via an Internet connection.

100% agree contributors would have to use source control (hence cut-down from Pro). Ideally via Git/Github (as Tim mentioned back in 2016) because it works well for distributed authoring.