Best practices for internal commenting in documents?

[Sarianna]

I'm trying to figure out a way to implement some kind of internal commenting possibility into Flare documents. The idea is that the same topics could be used to generate an internal, commented version for distribution within the company and a public version for customer documentation, in PDF and HTML formats. The comments here would not be a part of the review process but would be included with the otherwise finished documents (for example, notes on changes planned for future versions, detailed customer-specific requirements, and so on). Kind of like the teacher's edition of a schoolbook .

My preferred solution would be to tie a certain style ("CompanyInternal") to a certain condition (exclude the medium "CompanyInternal" from customer documents"), but based on searching Flare's help and this forum, styles and conditions cannot be linked like that. So although I did create a generic CompanyInternal style, with a bright pink background to make it jump out in case it slips where it's not supposed to go, there is also now a second, crucial step in the process, namely setting conditions for all internal text. Then I have separate build targets for output intended for internal use and output intended for customers. This could probably also be done with one target by toggling the include/exclude conditions, but I feel that separate targets are safer. So far I have only tested this method for a small test document, but it seems to be working as required.

I thought it might be useful to ask if anybody else here has implemented some kind of technique for a similar kind of internal commenting, and if so, what are your tips for best practices? I would really like to streamline the two-step process of applying internal style and internal condition separately into one step, but haven't figured out how. Any helpful hints?

[SteveS]

I think there was dicussion on this years ago...

I have created a style called rem (for remark, coming from a programming background...). This style is a green version of my usual font.

I have a condition, called REM, coloured green (is there a theme here?) that is excluded from all outputs.

Although the style is unneccessary, because the condition tag highlights the remarks, it makes me feel better, sometimes if the monitor is playing up it can be hard to see the subtle shading applied by a condition.

So, I write a remark, style it, then condition it. I try to keep this on the top of the page.

HTH

[Sarianna]

Thanks, Steve! It seems that basically your workflow is the same: both style and condition are used. Only the output strategy is different, because I do want one version of output with the internal comments visible.

Just for clarity: when you say "the condition tag highlights the remarks", by highlight do you mean just the color of the little tag at the left, or is there some way to make the conditioning highlight the entire text or background? That's what I would like, but have not figured out a way to make it happen except by applying a background-colored style separately.

[SteveS]

My bad, yes I use a background colour and dotted border to highlight the comment on the page. I also number the comments.

Code: Select all

p.comment
{
	font-weight: bold;
	color: #008000;
	border: dashed 2px;
	border-color: #ff0000;
	background-color: #90ee90;
	mc-auto-number-format: 'R:COMMENT {Gn+}: ';
	mc-language: none;
}

You can add the comments to a specific output by including, rather than excluding, the condition in the target.

[Msquared]

I think there are two sorts of comments, those that explain why something has been done in the content, which are there to help those who work on the content in the future, and those that mark areas where I have questions, need review etc.

I regard the former as permanent, and have a special Comment condition for those, which is always excluded from any output including review outputs. so I and anyone else working on the content will see it, but no-one else.

For the latter I use a style, which has a different (italic) font, and a coloured background. That style is hidden in my normal targets, and only shows up in my review targets. So if I don't get round to removing all of those before the content is published it doesn't matter.

[Sarianna]

Thanks for your replies! What a good idea, having a separate comment type for content-related things. Currently I am the only tech writer working on our material, but even so, I sometimes manage to puzzle myself with what I've written years earlier and subsequently forgotten the reasons for . While working in Word, I tried to maintain a kind of separate style guide for myself with hints and reminders, but it would be much easier to have them directly in context with the content they are related to.

[MPighi]

Hi all, I'm new here!

Condition is a good solution, an alternative would be to use the CSS display property to automatically exclude/exclude content based on the CSS media.

We use this solution and we find it very easy and fast for the writer!

[Titus]

I'm sure this is fairly well-known by now, and this thread is somewhat outdated, but (in addition to the previous suggestions) in Flare 12 you can create a style that has a condition applied to it automatically. So whenever you use that style (in my case, p.Comment), it is automatically conditioned (and excluded as per the Target properties). This means that the writers don't have to manually condition the comments, and you can style the comments in other ways so as to make it look more like a comment, i.e., put it in a bubble or change the background color, etc.

Edit: Page 206 of the Flare 12 What's New Guide.

[mwright123]

Hello,

How does one achieve this (applying a condition and a style, more specifically, a background color, at the same time) for a block of content that could include any number of different types of tags - headings, paragraphs, images, lists, etc.?

I saw Dave Lee's post on this for HTML 5 output here:
viewtopic.php?f=12&t=19801

as well as this one that links to it:
viewtopic.php?f=75&t=20487&p=109694&hil ... +tag+style

I am trying to create something in my CSS that I can apply, so that the selection is conditionally tagged ("Internal Only" condition) and has a light blue background color - so internal readers of the output -- HTML 5, PDF, and Word -- know when they are reading internal-only content.

I'm not really a CSS expert, so I am not sure how to implement this - I want to be able to "wrap" a bunch of tags with the condition and the style. I tried using a Generic Class, but this did not seem to work.

Any advice?

Thank you!
Mary

[ChoccieMuffin]

Could you shove all the things you want to apply the colour to inside a div and then apply your "internal only" style to the div? The problem with just applying the generic to other content is that if you want to apply more than one class to a tag you have to edit it manually in the text editor, which is very slow and error-prone.

[mwright123]

Hi ChoccieMuffin,

Thank you for the tip! I have just tried this, and it works great - so thank you very much! I was able to do this by manually creating the Div in the text editor, and then applying a Div.InternalOnly style to it (where the style has the bg color and condition tag specified).

2 related questions for you if I may:

1. Is there a quick way in the XML Editor to create the Div element? I did this manually in the Text Editor by modifying the HTML. Then, I went back to the XML Editor and applied the Div.InternalOnly style by using the right-click menu on the Div structure bar. I'd love to be able to stay in the XML editor - quickly select the group of elements and then do a-b-c to get it done.

2. In the Stylesheet Editor, I noticed there is a "div" element and a "Div" element. Every time I tried to create a class off of the div element, it popped me up to the generic classes. I was only able to create the "substyle" (if you will) on the Div element. What is the difference between the 2?

Thank you!
Mary

[wclass]

1. Is there a quick way in the XML Editor to create the Div element? I did this manually in the Text Editor by modifying the HTML. Then, I went back to the XML Editor and applied the Div.InternalOnly style by using the right-click menu on the Div structure bar. I'd love to be able to stay in the XML editor - quickly select the group of elements and then do a-b-c to get it done.

Yes - use the TAB key. Select the content you want, then click TAB, and the Create Groups dialog is popped up. You should be able to select a specific Div from the dialog.
"Create Groups" is also available on the Ribbon on the Home tab in the Paragraph section.

2. In the Stylesheet Editor, I noticed there is a "div" element and a "Div" element. Every time I tried to create a class off of the div element, it popped me up to the generic classes. I was only able to create the "substyle" (if you will) on the Div element. What is the difference between the 2?

Can't help you here - I only see the "div" element. Have you looked for it in your style sheet via the text editor rather than the Flare stylesheet editor? I find out more by jumping into the text editor.

[mwright123]

Thank you very much, Margaret! Your tip works great!

Cheers,
Mary