MadCap Software Forums

Hi all,

Have a fairly hefty challenge, and am not expecting an easy solution - but wondering about which approach people would suggest.

We have over 50,000 pages of field-level guidance (i.e each field has its own paragraph or more of information). A single record may have 100 fields on it (or more, or many less) , so 100 'chunks' of information for a single record, stored in a legacy system.

We managed to bulk convert each 'chunk' into a single flare topic, and even managed to then automate the link clicking on the field and bringing up the field-specific topic. Which would then enable us to link this field-level information to the wider user guides, training documentation etc that was separately ported into Flare. Fireworks, celebration, cigars all round, right?

Wrong. The users hated the fact that they only saw the information relating to that one field. With the old system, it used to bring up a page, with all 100 items of information, but bring you to that specific field within those 100 other fields. So - we've been forced back to maintaining the legacy field guidance system, not using flare for this area, having 2 documentation silos. Frustration all round.

I want to have another go. Clearly, we have to give the users what they want - all 100 fields visible on the same page. The question is then - should I have one topic per record, with 100 subheadings, and try to automate the system to open that page, and go to the appropriate subheading? or do I stick with one topic per record (my purist preference), in which case is there a clever way to easily publish multiple records on a single page? I know this can be done manually with the TOC, my problem is with scale / automation / governance - the conversion would need to be automated, and subsequent maintenance / enhancement would need to be automated or at least as simple and foolproof as possible.

How would you approach it?

Thanks.

Quick question...

Have you got a list of the topics in the order they should be added to a TOC to recreate the old style documentation?

Obviously I'm thinking about using Excel and a text editor to automate the process...

owilkes wrote:The question is then - should I have one topic per record, with 100 subheadings, and try to automate the system to open that page, and go to the appropriate subheading? or do I stick with one topic per record (my purist preference), in which case is there a clever way to easily publish multiple records on a single page?

I don't follow parts of your question:

* What's the difference between:
"should I have one topic per record, with 100 subheadings... or do I stick with one topic per record"

* What do you mean by a 'record', 'field' and a 'page' - you initially said you had multiple 'fields' in a 'record', then say you have multiple 'records' in a 'page':
"in which case is there a clever way to easily publish multiple records on a single page?"


Anyway, maybe set it up as follows:
- Have each chunk/'field' as a snippet, instead of a topic.
- Create a topic for each 'record'/page(?), and insert the appropriate snippets.
- Create your CSH links to the topics, using bookmarks for the appropriate 'field' snippet.

Thanks for responses, sorry for delay to responses.

I can get a list of the topics, in the correct order easily enough (as I say, there are around 40,000 of them across maybe 4,000 files - but I can extract that easily).

I'd be curious as to how you'd do it - I'm all for using Excel and text editors to do as much heavy lifting as possible...

Response to Dave Lee -
* What's the difference between:
"should I have one topic per record, with 100 subheadings... or do I stick with one topic per record"

Lets say I have a table called 'CUSTOMER' and on that table had fields 'ID' 'NAME' 'ADDRESS' and 'DATE.OF.BIRTH' - so I'd have a record like this

ID : 12345
NAME : FRED
ADDRESS : 1 NEW ST
DATE.OF.BIRTH : 19900101

In Flare, I had 4 topics - one explaining what ID is for, one for NAME, one for ADDRESS, one for DATE.OF.BIRTH.
Previously, we had a single page which held all 4 topics on it.

I need to give them what they had previously - i.e a single page, with all 4 topics on it. Either I need to merge the 4 topics back into a single topic (which I don't like, but ho hum) or I need to find a way of showing all 4 topics on a single webpage when someone clicks on the CUSTOMER table.

I see what you are suggesting, and will give that a try/thought as well. Is there any problem with having 40,000 snippets in the system?

Thanks.

owilkes wrote:Is there any problem with having 40,000 snippets in the system?

No more problematic than topics.

The point of using snippets is that they're actually designed to be inserted in topics, which appears to be what you want to do; e.g. your 'customer' topic would contain 4 snippets, one for each field. If the fields are used in multiple places, then the snippets could be inserted in other topics too.

Dave Lee wrote:The point of using snippets is that they're actually designed to be inserted in topics, which appears to be what you want to do; e.g. your 'customer' topic would contain 4 snippets, one for each field. If the fields are used in multiple places, then the snippets could be inserted in other topics too.

This is exactly what we do in one of my client's Flare projects. We've got hundreds of "field description" snippets and then we use those snippets in all the "screen-/window-level" topics for the UI screens/windows that show those fields. The UI itself is linked to the screen-/window-level topics for CSH.

owilkes wrote:...I'd be curious as to how you'd do it - I'm all for using Excel and text editors to do as much heavy lifting as possible...

Excel has quite a few text manipulation formulae, such as concatenate.

I quite often paste a list of file names/ paths into excel and use concatenate to build the lines of a batch file. I then copy and paste the info created by concatenate as values, then copy the values into a text editor to complete the process of making a batch file.

In your case I would open the TOC in a text editor and build the lines of code to match in excel. I would then create a copy of the TOC and add my concatenated text. Next, test!

Many thanks all, it works!

I've been able to convert the records to snippets, create a file which has thousands of topics which reference the snippets. The final challenge is to split this file into the thousand different records - but that is a separate tech challenge.

The larger challenge is then convincing the organisation to use this, and accept some change - but at least can prove it can be converted relatively painlessly.

Thanks again