dealing with TBDs

This forum is for all Flare related Tips and Tricks.
Have a tip or trick you use while working in Flare? Share it here.
Post Reply
yonatanlehman
Propeller Head
Posts: 51
Joined: Mon Sep 18, 2017 6:14 am

dealing with TBDs

Post by yonatanlehman »

As I write things keep popping up in my mind, like the need to add a term to a glossary or to reference a "see also".
In order not be distracted I want to add a TBC (to be done aka TBC) - a note to myself that I need to add something later.
The nature of the TBD is
1. I want to be able to search for current TBDs, so that I can deal with them
2. TBDs should only be visible in internal targets.

My first attempt to do this is the just type "TBD(some note to myself)", style it or condition it so that it only shows up where it should, and maybe highlight it as well. And then use the Find on the Home ribbon to find them.
Is there a cleaner/faster/cooler way to do this ?
paintedturtle
Propeller Head
Posts: 88
Joined: Wed May 25, 2016 3:35 pm

Re: dealing with TBDs

Post by paintedturtle »

yonatanlehman wrote:As I write things keep popping up in my mind, like the need to add a term to a glossary or to reference a "see also".
In order not be distracted I want to add a TBC (to be done aka TBC) - a note to myself that I need to add something later.
The nature of the TBD is
1. I want to be able to search for current TBDs, so that I can deal with them
2. TBDs should only be visible in internal targets.

My first attempt to do this is the just type "TBD(some note to myself)", style it or condition it so that it only shows up where it should, and maybe highlight it as well. And then use the Find on the Home ribbon to find them.
Is there a cleaner/faster/cooler way to do this ?

I use annotations as notes to myself, as I'm the only one who uses the content in Flare versus the output. However, it's difficult to search annotations in Flare, though I think you could search the code for it in Windows Explorer. But it's a good visual queue for myself that others don't see.
Technical Writer using and experimenting with Flare version 12.0.5991.
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: dealing with TBDs

Post by RamonS »

I use pen and paper or our bug tracking / backlog system. I don't think the Flare project is the right place for a personal to do list. Just my 2 €.
yonatanlehman
Propeller Head
Posts: 51
Joined: Mon Sep 18, 2017 6:14 am

Re: dealing with TBDs

Post by yonatanlehman »

Thanks for the replies
RamonS wrote:I use pen and paper or our bug tracking / backlog system. I don't think the Flare project is the right place for a personal to do list. Just my 2 €.
Maybe I wasn't clear - this isn't a to do list. Just a place holder within the text for something I want to add later at that point in the text (e.g. a reference, or add something to the glossary). This way I know exactly where I need it - if I write separate notes then I need to point to where in the project - more work and more error prone - no ? Or am I missing something ?
RamonS
Senior Propellus Maximus
Posts: 4293
Joined: Thu Feb 02, 2006 9:29 am
Location: The Electric City

Re: dealing with TBDs

Post by RamonS »

It is a matter of personal choice. With adding TBDs to the source you have the extra work of properly removing them later as well as properly inserting them so that they do not show in output. I find that quite risky. You also need a means of finding all the TBDs. I bet it is about the same level of effort in the end compared to jotting down the topic name and what you want to do.
I make call immediately with such work items. If it will take me less than half an hour to do I do it right away. It's done, no need to keep track of it, I can purge it from my mind. It also gets things to completion faster. Anything that likely lasts longer than half an hour goes into a task attached to a TFS backlog item. When I finished one unit of work I pick up one of the tasks before starting the next unit of work. If you have coworkers working on the project then it is an opportunity to distribute the work. Ideally, you want to keep that task list small. We use a second backlog item to attach completed tasks to, but that is only to appease project leads who get all freaked out when a task marked as "done" shows up in their queries. They could update their queries with ease, but .....
For anything that is outside the scope of project work I keep a hand written list in my scrap paper binder (yes, I'm the guy who goes dumpster diving for papers with a blank back....in my ten years now with the company I still am on my first paper notepad). I cross off things when I finished them and when it seems necessary rewrite and consolidate the list. At that point I also groom it. Some items become obsolete or I see them as unimportant after some time.

This worked for me since decades (yea, I'm old), but it is my personal choice. You may prefer a different approach.
ChoccieMuffin
Senior Propellus Maximus
Posts: 2630
Joined: Wed Apr 14, 2010 8:01 am
Location: Surrey, UK

Re: dealing with TBDs

Post by ChoccieMuffin »

I have a couple of styles which also contain conditions, and these conditions are excluded in all our final targets.

COMMENT contains comments that need to stay in the topic, for example "CSH for xxx dialog box. MUST be called Topic15432.htm because the devs refer to the filename instead of using aliases." I don't change the comments often, and don't add too many of them, but they're useful if I've put a project down for a few months and can't remember all the details, and that kind of thing means that if I've renamed a stupidly named topic to something sensible, when I open the topic I can see that it has to keep its stupid name. (Devs, dontcha just luv em!)

QUESTION is in red bold (really obvious if it crops up in output), and that is what I use to include notes for myself or pointers for reviewers, like "xxx this a completely new section, please review very thoroughly xxx" as they can sometimes be a bit slapdash in what they look at... :roll: or I put in "xxx insert x-ref xxx" when I know I'm going to want to include a cross-ref to a topic I haven't written yet but know I'm going to write. Just as a convention to myself I always include comments inside pairs of xxx, so I can do a search for "xxx" and all my questions will pop up, or I can search for "<span class="QUESTION">" in the source code. That, or questions come out in the wash when I get review comments and I delete them when I've dealt with the question.

And I have a specific point on my final output checklist to confirm that COMMENT and QUESTION are excluded from all outputs, just in case I've missed removing one.
Started as a newbie with Flare 6.1, now using Flare 2023.
Report bugs at http://www.madcapsoftware.com/bugs/submit.aspx.
Request features at https://www.madcapsoftware.com/feedback ... quest.aspx
smajors
Sr. Propeller Head
Posts: 180
Joined: Mon Oct 21, 2013 9:28 am
Location: Midwest United States

Re: dealing with TBDs

Post by smajors »

I take a similar approach as you do and write the TBD content in the topic and condition it as red "draft" text. Sometimes, I will add an annotation as a note to myself, then come back to it later and delete it. Either way, it stands out as something I need to address. But, then you have to remember which topics you added these notes to. I usually make a list on paper so I don't forget.

There is a Flare report you can run that lists topics with annotations. Perhaps from that report you can search for "TBD" items.
Technical Writer
Training & Development Team/Marketing Department
Post Reply