MadCap Software Forums

Hi All,

In my ideal/naive world, I would like my tech writers to write their documentation based on the specs, and then the testers to provide the screen snapshots that would accompany the text.

Realistically, the Tech writers will probably have to create the screen snapshots when the testers fail / forget to do so. Nevertheless, we want to write the documentation during phase 1 (design) and then add the snapshots in phase 2 (post-testing).

What I DON'T want to happen, is for any documentation to get to our clients with "Please Put a Snapshot of XYZ in here" appearing in the text.

I also don't want there to simply be some places where images are supposed to be, but someone forgot.

SO : What is best practice out there for tagging topics / sections within topics, with 'Not Finished Yet' - that can easily come out in a report, so I can check across the projects before we do a build?

Do people use conditional text (and then run the Applied Conditions / Used Condition Tags Report) ? Are there any cunning tricks people have used in the past?

Thanks.

We use conditions - that's the only way to keep the text out of the online output.
It's different with PDF, though: for that you can also use a class like .comment that you set to display: none. That generic class you can assign to any element, even to a selected text.

You can create reports in Flare showing you where conditions or classes ar used - give you a list of files.
You could even create more than one condition or class, depending on the purpose, e.g. MissingPic and Comment - that would make it easier for you to see where the holes are.

Invisible comments are a 100% necessity.
We need it for comments like:
if you change this, have a look at topicX.htm - you might have to change the reference there
or
do not touch - phrase comes from VIPs ...

owilkes wrote:What I DON'T want to happen, is for any documentation to get to our clients with "Please Put a Snapshot of XYZ in here" appearing in the text...

SO : What is best practice out there for tagging topics / sections within topics, with 'Not Finished Yet' - that can easily come out in a report, so I can check across the projects before we do a build?

I'd create a snippet file with some big red text that says to insert the snapshot, then I'd set a condition tag on the tag in that snippet (paragraph or DIV, for example). Then insert the snippet into the topic where the image should go. If someone forgets to replace the image, the condition tag prevents that snippet text from showing up in the output. Plus, I think you can create a report in Flare for instances where that snippet is used, although I don't have Flare open at the moment to confirm that. If that's true, then you could run the report before building the output to see where that snippet exists in the project (other than the snippets folder) and then replace the images. Even if you can't do a report, you can check the presence of the snippet manually by right-clicking on the snippet file and selecting View Links -- that will bring up a pane showing what files point to the snippet file.

LTinker68 wrote:Even if you can't do a report, you can check the presence of the snippet manually by right-clicking on the snippet file and selecting View Links -- that will bring up a pane showing what files point to the snippet file.

That's the way I would go, if I would want to insert the images now. In the link viewer window you can doubleclick on the files and open them straight away. In a report you get a list and you would have to find the topic in the Content Explorer all by yourself using the path given in the report.

Excellent suggestions, which make sense. I think I'll go for the 'snippets' suggestion, as that is easier to train a group of people to do, rather than the styling.

My only problem is the projects get so huge, the 'linked from' does often take ages to build - but we can find it through find in file easily enough.

Thanks for the help, knew there'd be some cunning solutions out there.

owilkes wrote:My only problem is the projects get so huge, the 'linked from' does often take ages to build - but we can find it through find in file easily enough.

Check out the reporting options. You might be able to build a report on the snippet usage and that might run faster than it takes to open the linked from dialog.

I also have created a style called remark, coloured green (I'm used to rem in VB). I insert a comment at the beginning of each topic explaining the topic background, why its there etc. I have a conditional tag for comment/ remarks that is excluded from all output and applied to the remark text.

I then use this for comments about work in progress for each topic. Its at the top, so you see it whenever you open the topic, and it helps my work flow.

HTH