A new tool to speed up production and improve quality

This forum is for all Flare issues not related to any of the other categories.
Post Reply
mpaquette
Propeller Head
Posts: 12
Joined: Thu May 22, 2014 1:35 pm
Location: Montreal
Contact:

A new tool to speed up production and improve quality

Post by mpaquette »

Hello everyone out there using MadCap Flare.

Technical writers need better tools. The Knowledge Management team at Intelerad has taken a step in this direction that we want to share with the Flare and technical writing communities.

We’ve been using MadCap Flare, also a better tool, since 2013. We like its simplicity and flexibility, including its use of XML and HTML. We took advantage of these things by building a tool that scans a MadCap Flare project for conformance to our style guide.

It's a modest tool but it helps us a lot, saving us production time, improving quality, and even training newbies. This tool doesn't overlap with MadCap Analyzer, but is really a complement to it. Example: our tool reports an error when a topic doesn't start with an h1 element.

We call this tool FlareLint and we’re releasing it under an open source license:

http://www.intelerad.com/flarelint/

System requirements:
  • MadCap Flare 8. It should work well with higher versions.
  • Microsoft Windows 7 or higher.
  • a Windows account with privileges to install software
  • Python 3. Instructions to install it are in the FlareLint documentation.
Download and try it. If it's helpful to you too, if you have feedback, or if you improve it, please let us know. Any suggestions are welcome.
Marc Paquette | Technical Writer
FlareLint is open source software to reduce production time and improve quality: https://flarelint.github.io/
mpaquette
Propeller Head
Posts: 12
Joined: Thu May 22, 2014 1:35 pm
Location: Montreal
Contact:

Re: A new tool to speed up production and improve quality

Post by mpaquette »

Thanks to our early adopters and their feedback, we're releasing FlareLint 1.2.

Features and fixes:

* Improvements to the user guide.

* In the HTML report, file names appear with their entire path. You can click the path to open the offending file in a new browser tab or window. You can copy and paste this path to edit the file directly in your favorite editor.

* FlareLint.bat prompts you to press any key only when there is an error in invoking FlareLint.

* You can inspect, add, and modify rules without mangling your Python installation or FlareLint installation.

* Rules may check for language.

* Rules are more easily customizable.

* Other small improvements to the FlareLint source code.

For full details and to send us feedback, see the user guide.

You can download the latest FlareLint here:

https://www.intelerad.com/flarelint

Thanks again for the feedback and I hope that FlareLint serves you as well as it serves us.

Marc.
Marc Paquette | Technical Writer
FlareLint is open source software to reduce production time and improve quality: https://flarelint.github.io/
NorthEast
Master Propellus Maximus
Posts: 6359
Joined: Mon Mar 05, 2007 8:33 am

Re: A new tool to speed up production and improve quality

Post by NorthEast »

I had a very quick look, and have some feedback:

* Put some information on your website about what this tool does, with examples, maybe even a video. There isn't much information there, which means you have to download it to read the documentation.

* I can see it uses 'rules' to check your project, but how do you create these rules? It looks like you need to know how to write code in Python - I don't, and I gave up at this point.


That's not meant to be negative - it's great that you're sharing your tool, it maybe just needs a bit more information on how to use it.
I'm not sure how many readers here will be that familiar with writing Python code, so might need help and examples.
mpaquette
Propeller Head
Posts: 12
Joined: Thu May 22, 2014 1:35 pm
Location: Montreal
Contact:

Re: A new tool to speed up production and improve quality

Post by mpaquette »

Dave, thanks for the feedback. I appreciate it.

To answer your first point: Like most teams, ours uses checklists for editing and for production. We need to ship quality, consistent content with no delays. So we do spell checks and peer reviews. Writers and editors are good at this.

We also check for things like an h1 element at the top of every topic, no body text after task steps, variables instead of product names, and so on. These things are tedious to check for, time consuming, and easy to miss. But when they slip through the cracks, they have a big impact on what we ship.

That's where FlareLint comes in. It takes a writer hours to find most of these problems. It takes FlareLint seconds with 100% coverage to report whether or not our targets are properly configured, boilerplate topics are in the right places in our TOCs, task topics are correctly structured, and so on.

Incidentally, FlareLint is not like MadCap Analyzer. Analyzer reports on the health of your Flare project. FlareLint reports on the adherence of your content to your team's writing style and conventions.

Your second point: You can get immediate results from FlareLint, out of the box, with no programming experience. Just install it and use it.

FlareLint comes with 26 rules for common "best practice" conventions. These default rules catch common but embarrassing things, like empty li elements, empty p elements, and topics that don't start with an h1 element.

After you're comfortable with FlareLint, you can customize it.

Does your team accept topics that don't start with an h1 element? No problem. A technical writer with no programming experience can add and remove rules by copying and pasting in Windows Explorer.

A more adventurous writer can customize FlareLint by tweaking the parameters in rule source code and editing the rule messages. You can also easily edit the CSS and HTML for the FlareLint report.

You can customize FlareLint as much as you want, including adding custom rules, if you convince a developer with a bit of spare time. A typical rule is only 10-20 lines of code.

Of course, you can also ask me for help, which I'm happy to offer.

Thanks again for the feedback. I'll add it to our wishlist for version 1.3.

Marc.
Marc Paquette | Technical Writer
FlareLint is open source software to reduce production time and improve quality: https://flarelint.github.io/
Cwestpha
Propeller Head
Posts: 49
Joined: Wed Jun 01, 2011 8:31 am

Re: A new tool to speed up production and improve quality

Post by Cwestpha »

Marc,

When trying to install, your MSI does not list the Python 3.6 from Registry option for me, only the Python from another location option. I installed Python 3.6 and it launches fine from Powershell. I also have Python 2.7 installed, I don't know if that throws a wrench in things or not.

What registry key is the MSI looking for?
mpaquette
Propeller Head
Posts: 12
Joined: Thu May 22, 2014 1:35 pm
Location: Montreal
Contact:

Re: A new tool to speed up production and improve quality

Post by mpaquette »

Cwestpha wrote: When trying to install, your MSI does not list the Python 3.6 from Registry option for me, only the Python from another location option. I installed Python 3.6 and it launches fine from Powershell. I also have Python 2.7 installed, I don't know if that throws a wrench in things or not.

What registry key is the MSI looking for?
Hi,

My guess is that you have the 32-bit variant of Python 3.6 installed, not the 64-bit variant.

Are you sure you installed the 64-bit variant of Python 3.6? The installer that currently fits the requirements for FlareLint 1.2 is here:

https://www.python.org/ftp/python/3.6.1 ... -amd64.exe

Let me know if this helps.

Marc.
Marc Paquette | Technical Writer
FlareLint is open source software to reduce production time and improve quality: https://flarelint.github.io/
marcinse
Jr. Propeller Head
Posts: 2
Joined: Thu Jun 21, 2018 8:28 am

Re: A new tool to speed up production and improve quality

Post by marcinse »

Dave Lee wrote: * Put some information on your website about what this tool does, with examples, maybe even a video. There isn't much information there, which means you have to download it to read the documentation.
(...)
That's not meant to be negative - it's great that you're sharing your tool, it maybe just needs a bit more information on how to use it.
I'm not sure how many readers here will be that familiar with writing Python code, so might need help and examples.
+1 to this.
The website looks nice, but there's hardly any info there on the tool - the installation process, requirements, supported platforms, screenshots or even what the tool actually does.
Most of what is in the manual in the ZIP file could be copied there.
PhilAmericus
Jr. Propeller Head
Posts: 6
Joined: Tue Feb 27, 2018 6:55 am

Re: A new tool to speed up production and improve quality

Post by PhilAmericus »

Hi. I like the tool. :) I've been playing with it for a little while and here's my comments about it:

1. It's nice having each rule in its own file. That makes is easy to remove rules that you don't need.
2. It doesn't run the way that the instructions describe. Instead of dragging and dropping the Flare project file onto the .bat file, I had to copy the .bat file into the directory with my project file and then just double-click the .bat file.
3. I would like to have the results give a line number. That would make it much easier to find the issue.
4. The rule that checks for hidden line breaks (flarelint_heading_linebreak.py) gives me a warning on lines like this one:
<h2><a name="_Toc502748886"></a>Initialization in the Direct Connection Mode</h2>

Thanks again!
mpaquette
Propeller Head
Posts: 12
Joined: Thu May 22, 2014 1:35 pm
Location: Montreal
Contact:

Re: A new tool to speed up production and improve quality

Post by mpaquette »

Hi marcinse and PhilAmericus,

Thanks for the feedback. I've taken note and added them to my list for the next release of FlareLint.

Question: would you be willing to beta test?

Marc.
Marc Paquette | Technical Writer
FlareLint is open source software to reduce production time and improve quality: https://flarelint.github.io/
mpaquette
Propeller Head
Posts: 12
Joined: Thu May 22, 2014 1:35 pm
Location: Montreal
Contact:

Re: A new tool to speed up production and improve quality

Post by mpaquette »

marcinse wrote:
Dave Lee wrote: * Put some information on your website about what this tool does, with examples, maybe even a video. There isn't much information there, which means you have to download it to read the documentation.
For a start, I've put the FlareLint 1.2 User Guide here: https://flarelint.github.io/

I've also created a public repository: https://github.com/flarelint

It's now easier for you to access FlareLint, send me feedback, and contribute to it. It also lets me inform you about the latest news on its development.

Latest news on its development: I'm working on an big update that lets you create and modify rules without the need for Python programming experience. This new rule "language" is much simpler, straightforward, and easier to use.

It's a leap forward to putting more power in a tech writer's hands. I'll keep you posted.
Marc Paquette | Technical Writer
FlareLint is open source software to reduce production time and improve quality: https://flarelint.github.io/
Post Reply