MadCap Software Forums

Hello all.

It seems that a lot of writers now take a docs-as-code approach where they write the docs in a text editor, compile using a static site generator (like Jekyll) and publish to a company server. I'm wondering is anyone has experience implementing the docs-as-code concept and how Flare supports this concept or not. As a long-time Flare user with all of my documentation in Flare projects, I'm not sure how to completely adopt the docs-as-code concept.

Currently, I generate my Help system locally and store all all my source files and outputs in Git. I commit, push, and then submit a PR to have our internal test site is updated with the latest Help. A developer approves my PR, deploys, and updates the Help on test site. My updates could take hours or days to appear on the test site, depending on a developer's availability. This workflow involves Git so it's sort of docs-as-code.

Ideal workflow: When I make updates as soon as I push any commits Git regenerates the Help via a static site generator like Jekyll and automatically posts the latest Help on the internal test site, all without involving a developer. When I've made all the commits for a release branch, I submit a PR. The commits on the branch are pulled to the main code branch in the Git repo. When the main branch is deployed, the Help updates are live for customers.

But I'm not sure how to get to my ideal workflow with Flare. Most static site generators support plan text source files like markdown files. Flare doesn't seem to allow export of clean markdown files.

Any suggestions?

There's a command line tool that I think can be integrated somehow with source control. I've never done it though. Something to look in to; at least some new words to search on the forum until anyone else with experience responds.

https://help.madcapsoftware.com/flare20 ... d-Line.htm

mdgates wrote: Currently, I generate my Help system locally and store all all my source files and outputs in Git. I commit, push, and then submit a PR to have our internal test site is updated with the latest Help. A developer approves my PR, deploys, and updates the Help on test site. My updates could take hours or days to appear on the test site, depending on a developer's availability. This workflow involves Git so it's sort of docs-as-code.

That sounds a bit more complicated than it needs to be. Is the developer just approving the pull request? No review or testing on it? If all the developer is doing is a rubber-stamp of the PR, get rid of that step and just deploy the new help when the testing is done.

Ideal workflow: When I make updates as soon as I push any commits Git regenerates the Help via a static site generator like Jekyll and automatically posts the latest Help on the internal test site, all without involving a developer. When I've made all the commits for a release branch, I submit a PR. The commits on the branch are pulled to the main code branch in the Git repo. When the main branch is deployed, the Help updates are live for customers.

I don't understand why you're using Jekyll (as a sort of wrapper?) for the Help. Why not just deeply the Help? What does using Jekyll get you? Why do you want to use Flare in a non-Flare way?

But I'm not sure how to get to my ideal workflow with Flare. Most static site generators support plan text source files like markdown files. Flare doesn't seem to allow export of clean markdown files.

Any suggestions?

I would try and simplify the workflow. Flare can import markdown. There isn't a markdown target, which is what you want. So why use Flare? I've worked with docs-as-code (https://success.jitterbit.com) but Flare wasn't involved.

Thanks for your ideas. Trying to streamline the approval process is a good idea.

How to use Flare in docs-as-code? That's my dilemma. If I could export the source files in markdown or another plain text format from Flare I could use the resulting files in Jekyll and then replace Flare with Jekyll as my generator. But Flare doesn't have an option to export markdown. So that's not going to work.

But I may be able to automat some of the builds. Good suggestion.

I'm still trying to figure out where Flare fits in the docs-as-code paradigm.

mdgates wrote: I'm still trying to figure out where Flare fits in the docs-as-code paradigm.

I don't think it can. And trying to fit Flare into a docs as code framework likely won't work. (But I would love to be proved wrong!)

Maybe this will help
https://idratherbewriting.com/blog/madc ... ease-2021/

Flare's has no position there.

Flare should be at the top of that toolchain with Markdown files as import objects. Markdown barely provides basic text formatting and isn't a suitable tool for writing documentation that needs regular updating, material needing more than basic formatting and tables, or material requiring extensive cross-referencing. Static Site Generators let people create source files in plain text using some flavor of Markdown and many, many macros in a vain attempt to mimic a few of the features offered in Flare. Heck, even Word does a better job.

If you look at the descriptions for those tools (Jekyll, Hugo, et al), you'll notice they are categorized as "Static Site Generators. "Static" being the operative word. Developers look at markdown and consider it suitable for docs. And it's fine for very, very basic docs that require almost no formatting. They are called "static" because the content was supposed to be "dead," as in needing very infrequent updates.

If you work a markdown shop, you'll be coding as much manual html as you do content just to workaround Markdown's shortcomings.

Project link checking
Only after building - There's no tool to link check unbuilt projects, no analysis tools, and hence no reporting. The only saving feature (at least in Hugo) is the generator's ability to render the site and serve it to you locally as a preview

Cross-references
Most of the things you take for granted in Flare (and yes, even in Word), such as creating pretty cross-references (e.g., "See Section 1.1.1, "Distributions," on page 32") in a couple clicks (or several clicks in Word) can't be accomplished in Markdown without resorting to coding.

List Handling
Generators only manage very basic bulleted or numbered lists. You can create sub-lists under an item, but that's it. You cannot, for example, use an additional paragraph for a Numbered list item:

1. This is my list
2. Some day soon <----- Feature name?
This feature provides blah, blah <---------- Placing a non-list paragraph in a list resets its numbering

1. Now is the <---------------------- The above paragraph reset Markdown's memory of the list beginning.

Ordered Lists in html is the workaround.

Tables

Tables are manual work unless you build them in a word processor and then use an online converter to generate the markdown.

* Generated Markdown tables don't support row and column spanning (which even Wiki does).
* Can't handle multiple paragraphs or lists (a newline breaks the table formatting)
* Fancy cell shadings beyond basic greenbar
* Shortcodes may or may not work inside tables

Html tables are the workaround

Footnotes
Generators do a nice job with footnotes. Easy to place.

Inserting referenced content onto a page ("including material by reference)
Has many limitations:
* Calling page type
* Location on the page (not in tables/lists)
* The target file location can be dictated by the access method. (You might need to store the file to read in a very specific location in the file tree).

You might guess that I'm not a fan of markdown. It can do the job, but man alive, is it ever labor intensive. I've lost days searching for and implementing/testing workable useable shortcodes/partials, or troubleshooting why a shortcode/partial doesn't work where I placed it. I'm a gnat's hair away from convincing them to migrate to Flare. None of the SMEs are what you would call happy working in markdown. They know It'd be easier/faster to provide their input in a word doc or plain text file and pass it along. They have five silos of markdown docs they want interconnected presented as a unified doc and Markdown isn't going to do that anytime soon.

Thanks. My goal is to reduce the delay between pushing changes to the Help and the changes displaying on a site where QA can review. Rather than involving markup or trying to build on a server, I can probably accomplish this via streamlined approval process.

Thanks for all the good insights, including the downsides of markup. Maybe a reason so many writers use the markup/static site generator combo is they don't have a better tool like Flare. Pure speculation but maybe they're making do with existing and free tools. I'll stick with Flare.

sarrantsvt wrote:

mdgates wrote: Currently, I generate my Help system locally and store all all my source files and outputs in Git. I commit, push, and then submit a PR to have our internal test site is updated with the latest Help. A developer approves my PR, deploys, and updates the Help on test site. My updates could take hours or days to appear on the test site, depending on a developer's availability. This workflow involves Git so it's sort of docs-as-code.

That sounds a bit more complicated than it needs to be. Is the developer just approving the pull request? No review or testing on it? If all the developer is doing is a rubber-stamp of the PR, get rid of that step and just deploy the new help when the testing is done.

I know this is a side bar, but in some organizations you can't commit to the origin or main branch directly. You have to submit a pull request and it has to be approved. Half of our company functions this way. All work is done in feature branches, and to merge a feature branch with origin you have to do a PR. That makes it so origin is always deployable. It doesn't get in to origin half-baked. This product deploys to production every night so you don't want half-baked content going into origin.

mdgates wrote:Thanks. My goal is to reduce the delay between pushing changes to the Help and the changes displaying on a site where QA can review. Rather than involving markup or trying to build on a server, I can probably accomplish this via streamlined approval process.

Thanks for all the good insights, including the downsides of markup. Maybe a reason so many writers use the markup/static site generator combo is they don't have a better tool like Flare. Pure speculation but maybe they're making do with existing and free tools. I'll stick with Flare.

Half my company authors in markdown and uses a static site generator to build their content. The other half uses Flare.

In both cases,we use a CICD (continuous integration continuous deployment) tool called Jenkins. We also have a server sitting out there with a Flare Build license. (Build licenses are licensed at a lower rate specifically because their only job is to build Flare projects from the command line.) Jenkins sits out there on its own server, and it has jobs to do. For our Flare-based doc repo, Jenkins has a job to check a specified branch of our GIT repo every 10 minutes. If there has been a commit to that branch in our repo, Jenkins reaches out to our Flare build server and tells the build server to run against that branch and build a specific target. (We use a batch target so we don't have to send several commands to be built separately.)

The Flare build server runs from the command line and builds the specified batch target for the requested GIT branch. Each target in our batch target has a destination, and as part of the command-line build, Flare publishes to those destinations. Those servers are our review servers, and can only be seen inside our organization.

The short version is that using Jenkins and a dedicated Flare build server, we check for updates to our repo every 10 minutes and build the latest content for our reviewers. Factoring in the build time, the build on that server is never more than 30 minutes old.

For our non-Flare half, they use markdown specifically because they publish to a bitbucket repo (like an internal github), and they need to be able to accept contributions from reviewers who are not part of our department, and who have no idea what Flare is, never mind a Contributor license. In this case, markdown is by far the better choice because your reviewers don't need to know anything about Flare. They have to submit a pull request, and a member of our team reviews the pull request and accepts it or suggests changes. This is wonderful because a reviewer makes changes directly to the markdown file and if it is a good change, all we have to do is approve the pull request. Everybody is working from the current source of truth, so you don't get out of sync on reviews.

They also have a Jenkins job that builds their feature branches so they can be reviewed after every checkin. Once the feature branch is finished, the writer submits a pull-request to get it into the origin branch where it will be build for customers to see it.

I hope that makes sense. There are distinct advantages to a text-based static site generator, especially if you are publishing to a public repo like github. There are distinct feature advantages for both the author and user when you use Flare, including content reuse (among man others). So it comes down to what is more important for your product. In our case, one product needed the markdown approach and the other product needs the Flare appropach. They are just different tools in the toolbox to solve different problems.

mdgates wrote: Thanks for all the good insights, including the downsides of markup. Maybe a reason so many writers use the markup/static site generator combo is they don't have a better tool like Flare. Pure speculation but maybe they're making do with existing and free tools. I'll stick with Flare.

Devs created static generators because they realized wiki (even though it was nice and manual) wasn't quite powerful enough and since they like coding ad hoc features in an attempt to mimic the features and tools that writers who use real doc tools already have. They aren't happy unless they can write scripts and treat the doc publishing system as though it were another coding project. I don't have time to build wheels. Devs recreate wheels for fun.