editing for automatic builds

[kristil]

I have a question for people who do automatic builds of their help systems. If you are updating a couple of topics at a time and pushing them out to users once they're updated, how do you manage your quality reviews for those topics? We are thinking of building WebHelps in this way, but we want to make sure when writers are doing things like tweaking the TOC and adjusting the arrangement of topics that we can catch any errors that may result before the auto build pushes it out to the world.

The rough idea we have so far is that we would write in one project, then release those topics to the project from which we will autobuild. So, have a production environment and a live environment. But I'm sure there are plenty of details beyond that. I'd love to know what is working for other people.

Kristi

[forfear]

we don't do quality reviews.

the writers do the best they can and wait for feedback. haha!
seriously
i suppose an occasional spot check and sampling could help
making the batch builds simple, modular and command line menu, GUI like simple could help.
make a standard operating procedure out of it.
run it through a few times, and refine until it works lovely.
assign a chap to run analyzer and run 3-4 reports on the projects that have changed - but ultimately make the responsibility the project owner themselves - so writers take responsibility over changes and final output ultimately.

[RamonS]

Treat the help the same way as the application code. That means before a build leaves the company QA has to sign off on it and support is not using its veto. The application is an organized array of programming language instructions. The help is an organized array of (English) language instructions. Aside from the type of language used, they are one and the same for a similar purpose. So apply any QA process for the application to the help as well.

[kristil]

I should have mentioned that we have a pretty thorough quality check. Right now, our help systems are installed as part of the software, and are only updated if the user takes an upgrade. I'm trying to picture how our stringent, slooow testing process will change once we get away from that and move towards providing the help separately, which will let us provide updates much more frequently.

Forfear's Analyzer suggestion could be good for us. Some sort of periodic, batch testing. Thanks, guys.

[RamonS]

So there will be changes to the help, but no changes to the application? Or will the change cycle for the application become shorter as well? If yes, I wonder why that is because you usually want to keep releases as infrequent as possible. Where I work we release twice a year with a maximum of three bug fix releases at scheduled dates (unless the customer is really dead in the water and needs a fix asap). One release is usually light on new features, because customers need to file state reports and don't want to be sidetracked by changes in functionality. If that wasn't the case we probably would release only once a year. So, if the app doesn't change the help doesn't change either. My guess is that I'm missing something here.

[kristil]

We are advocating to divorce the help files from the software files. They'd be installed at the same time--we'll want to provide updated help at the same time as updated software--but the hope is that we can get a couple of things out of doing this.

1)We can edit content closer to the delivery date because we can lighten the internal editing and testing that we do just before release.
2)Our goal is to update at each patch, where it makes sense, so this lightened testing load can really add up for us and make that goal more feasible.
3)Less push-and-pull with with programming to get our files included.
4)We're regulated by the FDA, so if we have an emergency edit, we can correct the help files, as well.

I'm new to this idea, so there may be other benefits I'm not aware of. I doubt we'll end up with significantly more releases, just better ones. Right now, we stop writing 2-4 weeks before a release is done being coded, so we miss things.

[RamonS]

Maybe the FDA regulations change things in some way, I am not familiar with those rules, but I do think that the help files don't have to be disengaged from software. Automatic build processes can include automatic builds of the help pulling the sources from source control using a specified label, branching, or other means of getting the right set of files.
We run sometimes builds until a few days before release, often enough to get the docs in, but nothing about the application code changed. The only difference from an application viewpoint is a different build number in the About screen. So I don't understand why point 1 is not possible right now.
Point 2 doesn't strike me as a problem either. How does the software code get distributed in patch builds? Since it is the same installer you have to marry those two together at some point.
Point 3 is a non-issue with automated Flare builds. The biggest obstacle for that is the need of an extra Flare license for the build server. Many have complained about it and I proposed a long time ago that MadCap should provide a compile-only version of Flare that can only do CLI compiles and nothing else and, of course, not require an extra license.
Point 4 makes me wonder, would an emergency edit only apply to the docs? No changes in the app?

The only thing I can see of a benefit is to really divorce app and help, making the help have its own installation routine that gets distributed as its own product. The problem here is that customers may only bother updating the app and not the docs.

I have the impression as if I misunderstand something here. In regards to QA, you can handle it any way you want. We do a full system test for the major releases, but do only spot checks for update builds. The update builds often only address issues for specific customers. For most others the disruption would be too big, why install a minor release when the current release works fine for them. Once in a while we have dot releases that are adding a very specific feature only, typically something that was descoped from the major release or that couldn't get done in the regular release cycle because developers were not available. So we do add changed docs to those releases as well, but we have a fully automated build system for the installers that compile the software and package everything up. The developers wrote a browser front-end for that system so that everyone with access can run builds for every product. The help gets pulled in from a network share because our TW uses Frame and WebWorks and as far as I know that doesn't have command line build capability. That is why there isn't much sense to add the help sources to source control (the project files are on a network share with proper backups). If I would be TW in our company I'd be using Flare and mandate to have the source files included in source control. And if the devs would be deadly against that I'd roll my own, but in the end have the automatic build pull the right files.

[DurtyMat]

For those of your wondering, the Flare EULA does allow you to install on two machines (at home or portable machine and a work or desktop machine). I can't believe I read the EULA. I can not believe I read the EULA.

so just install a copy of flare on a server for automated builds, unless every copy of flare is on two computers right now ....

[kristil]

Hi, Ramon-

Maybe the FDA regulations change things in some way, I am not familiar with those rules, but I do think that the help files don't have to be disengaged from software. Automatic build processes can include automatic builds of the help pulling the sources from source control using a specified label, branching, or other means of getting the right set of files.

We get audited by the FDA, so we have to demonstrate that we follow our quality processes. Currently, our process states that our SMEs sign off on the final files. And before we can call a file final, it has to be the file that passed our internal quality review. Both reviews combined take several days, and we have to build time into that schedule to allow for rebuilds, should they be necessary. On top of that, our programming teams require the files for installation a minimum of two weeks in advance of a release. We're working on that, though. The best we've done is one week, which still sounds longer than what you're talking about.

This issue of internal testing also prevents automatic build and publishing of the files, currently. That's because we would be automatically installing files that have not received final SME approval. So that's an issue we should solve before we start asking the programmers to provide a location and a process for us to get automatic builds included. For now, we give them the files and they install.

You mentioned earlier in the thread that you use a QA process to test documentation. We use an internal QA process for the help file and print manuals, then turn it over to programming, where the help file is tested as part of the larger QC process to make sure the file is installed correctly, including context-sensitive help. I'm curious to get a better idea of the difference between what you're doing and what we're doing, because it sounds like you are getting faster turnaround.

[KevinDAmery]

When they do an automatic build, where are they getting the help files from? If it's some sort of source control, you can deal with this by having the writers only check documentation updates into source control after they have been approved by the SME (this would be similar to a developer only checking code in after that developer has completed their unit tests and is confident it will work). Any doc updates that have not been reviewed would not be checked in yet, so the automatic build system wouldn't have access to them.