Using Flare for Something OTHER than Online Help?

[ktbCA57]

My boss just came to me and asked me the following "Is Flare an appropriate vehicle to store and build our Systems Documentation?" i think he might be referring to requirements docs and those kinds of things...

Does anyone have any input or perspective on this?

Thanks!

[KevinDAmery]

In theory, sure. In practice, it depends on what your company's requirements are.

For example, I create our policies and procedures docs in Flare then build to Word. I could also create the documents directly in Word - the primary advantage to using Flare for these docs is, well, I don't have to use Word

[doc_guy]

Flare can also be used as a knowledge base very easily (see MadCap's knowledge base for an example).

One of the problems for using Flare as a requirements tool, is that the WebHelp output isn't editable by other people. If you have feedback server installed, then people can comment on the topics, but most requirements tools let you define the scope of the requirement (which an authenticated user can change on the fly) as well as link the requirement to other requirements. You wouldn't get any of that.

I suppose it is a case of "yeah, we could do that, but we wouldn't be able to do it as well as a requirements-specific tool."

If all you have is a hammer, then you can probably make a hammer work. But this seems to be a case where you need a pipe wrench, not a hammer. They don't do the same thing, but if you bang hard enough, maybe you'll make it work well enough. And maybe you'll just break the pipe, causing more damage than good.

[doc_guy]

However, if it is just a place to archive systems docs, including requirements docs, then you can probably make it work just fine.

[RamonS]

It is also a nice vehicle to serve up any kind of digital document without making it look like crap. Knowledge bases are a perfect fit for a HAT...which is is why so many folks don't use it and assign KB maintenance to one person who is damned to use a wiki. Speaking of experience here and frustration since the wiki doesn't have full text search.

You can also make web pages with it by crafting WebHelp and then stripping away whatever you don't want. Doc_guy's website is a nice example for that.

[DocuWil]

And .... what do you think about functional test documents.
I use Flare for that purpose since a while.
Test documents maybe built up of dozens of small topics.
Example:

stp-preparations.png

stp-actions.png

The advantage is especially with global linking, where you can put common used STP (Software Test Protocol) topics. At least, in my company several software tools are developed having basic things similar, like login procedures, table grids, the Help (Flare's Webhelp of course), etc.
In my case the output is always a Word document, because then the whole STP can be carried out digital. I hope, however, that the output can be done more PDF like; that is, the tester should only enter a mark Passed or Failed and if necessary some comment.

[RamonS]

Test plans in Flare...now that is clever. The problem is that every tester needs Flare installed in order to document the tests....or do you do crazy stuff like filing that on paper? Maybe that is required for the tests that you run.

[KevinDAmery]

Test plans in Flare...now that is clever. The problem is that every tester needs Flare installed in order to document the tests....or do you do crazy stuff like filing that on paper? Maybe that is required for the tests that you run.

Depends how often your plans change. If I'm reading DocuWil's post correctly, they create the templates in Flare and compile them to some other format, then the testers work off the compiled version. I don't think they're using Flare to record the results for each build (but I may be misreading that). If I'm right, then it's no different than any other doc: the technical writer makes updates as required and rebuilds the target whenever the test procedures are refined.

[DocuWil]

Thanks Ramon,

The tester gets the Word Output at my place.
Suppose there is the document: tooltotest_sv2.3_r1.doc
sv2.3 = software version 2.3
r1 = document release 1

Let us say Peter Jansen executes the tests. Normally he only puts a cross in Passed or Failed and if needed he writes some comment on the line preceded with the word Comment.
He saves it as tooltotest_sv2.3_r1_pj.doc. So we know that the product is tested and by who.
If there are things which I did not write correct in the test then I can change the specific topic and the output to tooltotest_sv2.3_r2.doc
If that specific topic is something general I change it in the source project, e.g. TestProtocols Source, to which my tooltotest project is linked.

But .... I have to say, at my company I am the only one making documentation, test protocols , etc. This forces me to work as efficient as possible.
And, as I said, it is functional testing. Simple said: push the button and look what is coming out. All between is not of interest.

By the way, of course I also make use of snippets, e.g. the snippet Action inserts automatically the Action complete the table Expectation and the line Comment. The number is also automatically increased within the topic. With a new topic it restarts of course.
I have also a snippet for the table Expectation, because you sometimes need different expectations for 1 action.
For instance, the header could be Expectation Dialog box and the following one Expectation Preview.

Anyway, a lot of things could be done for Test Protocols.

[RamonS]

Really interesting! I work as a QA analyst and I'd never would have thought that there might be any point to having someone else write test plans other than QA staff. But then again, a lot is gained from detailed test plans. We have some old plans where the action item is a question "Does the reporting work?" - and that's it for testing the report generator. We've done much better in the past years and we start to appreciate our test plans more and more (btw, we use Excel, my proposal to use something else was voted down early on).
Nice spin to have a tech writer craft the test plans, they probably come out better that way and are more consistent (some of us don't like to write as much as I do). I always think that the tech writer needs to be as much tech as he/she is writer. I've met a good share of "tech writers" that have no clue about tech other than Frame, so they are more "formatters" than writers or even tech writers. And since the tech writer needs to do everything at least once anyway, why not have him or her report bugs as well. Writing the test plans is taking this to a whole new level. The only downside I can see here is that the QA folks don't own the test process entirely. It becomes to easy to only go by the book and not look left or right, although that depends on the team that was hired.
I will keep that in mind, this is really an interesting approach. Thanks for mentioning it.

[KevinDAmery]

Really interesting! I work as a QA analyst and I'd never would have thought that there might be any point to having someone else write test plans other than QA staff. But then again, a lot is gained from detailed test plans. We have some old plans where the action item is a question "Does the reporting work?" - and that's it for testing the report generator. We've done much better in the past years and we start to appreciate our test plans more and more (btw, we use Excel, my proposal to use something else was voted down early on).
Nice spin to have a tech writer craft the test plans, they probably come out better that way and are more consistent (some of us don't like to write as much as I do). I always think that the tech writer needs to be as much tech as he/she is writer. I've met a good share of "tech writers" that have no clue about tech other than Frame, so they are more "formatters" than writers or even tech writers. And since the tech writer needs to do everything at least once anyway, why not have him or her report bugs as well. Writing the test plans is taking this to a whole new level. The only downside I can see here is that the QA folks don't own the test process entirely. It becomes to easy to only go by the book and not look left or right, although that depends on the team that was hired.
I will keep that in mind, this is really an interesting approach. Thanks for mentioning it.

Just to add to this thought process:

I think the best approach would be for the testers and the tech writer to work together on it, with the testers taking on the role of SME regarding testing procedures.

1) The testers and the TW sit down and determine what all the tests are.
2) The TW writes a detailed test plan
3) The TW and testers review the test plan and update as appropriate
4) When the testers identify a new test scenario, they submit it to the TW
5) Repeat from step 2 for the new scenarios

So the document can change regularly depending on the results of testing or on new feature requirements, but at the same time you have a defined process for the testers to follow to ensure that no tests are missed and that if necessary the testing team can demonstrate that they have a solid process to management or to other departments.

[DocuWil]

Hi Kevin

1) The testers and the TW sit down and determine what all the tests are.
2) The TW writes a detailed test plan
3) The TW and testers review the test plan and update as appropriate
4) When the testers identify a new test scenario, they submit it to the TW
5) Repeat from step 2 for the new scenarios

It will not suprise you that this is almost exactly the way we work, except that I often also coöperate with the software engineer, as we are a small company.
The nice thing is that the software engineer can get another look to the product, because the tests are much more dedicated to the end-user. So, user-friendness and more logical operation are going to play a role.
Sometimes it is difficult to have requirements. For instance, there is a kind of an idea. Then one of the software engineers starts developing a very basic piece of software. I start writing a little bit documentation with the application in front of me. Next, we sit together (sometimes also with a special customer), change some things, add some things, and so on. All is very interactive. Finally, we got something satisfying and guess what. That will be the blue print for testing. Of course, it is a mad looking-glass world, but it works.

[KevinDAmery]

Oh, I know the feeling. In a lot of cases, our development is based on verbal instructions in a 10 minute meeting with the company owner (we have 8 people here, only two of which - the developer and myself as TW and tester - actually work on developing the software). We are in the process of ramping up to a larger development team in conjunction with another company, so our processes will be getting tighter as we go forward (believe it or not, everything so far is actually being planned properly).

[ktbCA57]

THANK YOU ALL for your input on this topic... I put it all in a document - listing all of your ideas and submitted it to Mgmt yesterday.. you helped them decide we should mainly just stick to using Flare for online help purposes!

THANKS TO EVERYONE.. YOU GUYS ROCK!

[forfear]

We use it for
Help,
Installation guides
System Requirements (Word/PDF) and
Webhelp for Intranet reference. (its source for copying and pasting professional tech writer created text for reuse in other business proposals/brochures/etc)

[Rona Kwestel]

We are trying to decide how to deploy a knowledge base, and since Flare's WebHelp output is one option, I thought I'd resurrect this discussion.

Currently, we have a KB that we distribute as a folder of Word-to-PDF files with one Index document listing all the articles, along with our other software documentation. Additionally, we have a "FAQ" folder in our legacy RoboHelp output that contains a series of KB-like topics. This is a result of different decisions at different times on how to manage this kind of material, and we now need to consolidate with a better solution.

I'm partial to including the KB as part of our help file, so that in cases where the more esoteric topic could make a useful reference to some of our standard help, it can be easily linked. Additionally, I like the idea of managing all the documentation under one system.

One of our developers, however, prefers the idea of using SharePoint as the way to deploy KB articles, but then they still need to be maintained as Word/PDF docs. However, one issue that favors SharePoint over Flare is that some of the KB documents that we deliver in the folder of PDF files also have auxiliary files that they reference, such as Excel spreadsheets or XML files containing output examples from our software, and I'm not sure how I would incorporate those into a Flare project.

Also, RamonS states the following:

Knowledge bases are a perfect fit for a HAT...which is why so many folks don't use it and assign KB maintenance to one person who is damned to use a wiki. Speaking of experience here and frustration since the wiki doesn't have full text search.

But in my experience, and as per this thread: http://forums.madcapsoftware.com/viewto ... =13&t=9724, I have not found Flare's WebHelp output to support full text search either, unless you resort to using the Madcap Toolbar, which I find to be a poor solution to the problem.

[LTinker68]

But in my experience, and as per this thread: http://forums.madcapsoftware.com/viewto ... =13&t=9724, I have not found Flare's WebHelp output to support full text search either, unless you resort to using the Madcap Toolbar, which I find to be a poor solution to the problem.

I think you get better results if you use WebHelp Plus as the output instead of just WebHelp. For instance, go to MadCap's KB at http://kb.madcapsoftware.com/, which I believe is WebHelp Plus output. Do a (unfiltered) search on the word Context. It returns several responses. Around response #11, you'll see a topic titled "Using Custom Redirect Pages and Custom Language pages". If you click on that topic, you'll see that the word Context was returned inside of the string this.Context.Request.UserLanguages. I believe that's the type of search you mentioned in an earlier post that you're looking for.

EDIT: It looks like it doesn't do partial-word searches (e.g., searching on cont instead of context), unless I used the wrong wildcard, but you don't really want your users to have to use wildcards. So, yeah, the searching could be beefed up a bit.

[NorthEast]

One of our developers, however, prefers the idea of using SharePoint as the way to deploy KB articles, but then they still need to be maintained as Word/PDF docs. However, one issue that favors SharePoint over Flare is that some of the KB documents that we deliver in the folder of PDF files also have auxiliary files that they reference, such as Excel spreadsheets or XML files containing output examples from our software, and I'm not sure how I would incorporate those into a Flare project.

Who actually maintains the KB articles? If developers/others need to maintain the documents, then having them in Word may be the only option (if they don't have access to Flare). If you maintain the documents yourself, then it is up to you what tool you use - Flare can generate help or PDFs.

As for the auxiliary files, you can include Excel spreadsheets and other files in a Flare project, and link to them from topics. If these files need to be updated or maintained by someone else (without requiring a rebuild of the help), then you could store them in a location outside of the project (including a sharepoint site) where you could link to them from the KB topics.

Also, if you need your PDFs and spreadsheets to be searchable, then have a look at WebHelp Plus too (it needs to be run from a Microsoft IIS Web server though).

[KevinDAmery]

One of our developers, however, prefers the idea of using SharePoint as the way to deploy KB articles, but then they still need to be maintained as Word/PDF docs.

Speaking as the guy who got stuck administering our SharePoint system here, I would ask if that adventurous developer was also volunteering to manage the system? Or were they going to let you do that?

In my experience, the people who like SharePoint the most are those who actually touch it the least. Word to the wise.

[Rona Kwestel]

Who actually maintains the KB articles? If developers/others need to maintain the documents, then having them in Word may be the only option (if they don't have access to Flare). If you maintain the documents yourself, then it is up to you what tool you use - Flare can generate help or PDFs.

Mainly I maintain these articles, though there is some argument that if they were managed on, say, a Wiki, it would be easier for other subject matter experts to edit them. However, in practice, this rarely happens, and I almost always need to go over them to fix formatting and style issues.

As for the auxiliary files, you can include Excel spreadsheets and other files in a Flare project, and link to them from topics. If these files need to be updated or maintained by someone else (without requiring a rebuild of the help), then you could store them in a location outside of the project (including a sharepoint site) where you could link to them from the KB topics.
Also, if you need your PDFs and spreadsheets to be searchable, then have a look at WebHelp Plus too (it needs to be run from a Microsoft IIS Web server though).[/

These files may need to be maintained by others, but the benefit of having them be searchable by using WebHelp Plus (which I hadn't known before) is worth the extra effort to store them in the project, which we'll keep in Perforce so others can still access them. One idea I just had is that if we number these KB articles, which we don't currently do, but seems to be standard practice, then we can create a KB auxiliary file folder in the project, under which are subfolders labeled with the article numbers, making the connection to the relevant article clear.

Speaking as the guy who got stuck administering our SharePoint system here, I would ask if that adventurous developer was also volunteering to manage the system? Or were they going to let you do that?

In all fairness, this developer does actually do a lot of the maintenance of our group's branch of the company-wide site, but yes, it would be up to me to manage it if we had all of our KB articles there, and I agree that it can be tedious to use.

[navoff]

We use it both as online help and customer documentation (PDF) but also for internal build and test procedures for our products (in PDF format). For one (and why only this one, I don't know) they decided they also wanted to have a checklist to verify the guys putting the hardware/software together are doing all the right testing. So, I created a check list that maps to each part of the process and even included a link to the page where the step is documented (it prints the page number in the PDF file). The nice thing is that using it for the build and test procedures means being able to create customized documents for all the variations of our products. The guys building it don't have to think about which steps need to be followed and which ones skipped because the document is specific to what they are building. A lot of the initial steps are the same regardless of the product being built so I can re-use those topics. Plus, it makes it easier to create a new document for a different variation of existing products. I just add or delete topics as needed in the product-specific TOC.

[DocuWil]

Sounds interesting navoff.
As you may have read earlier posts of this subject you can see that I also am interested in this matter, especially functional testing.
And in the meantime I have some new ideas.
Do you have an example how you have set upp some things?
After all, it is a little bit forgotten subject and it should be nice if we could create a PDF with input fields to provide a tester with a digital document.
Now test documents have to be printed (often a lot of pages) to write comments by the tester and have it signed off.

Thanks for your input