Regular importing of Markdown files

This forum is for all Flare issues related to importing files or projects.
Post Reply
JHine
Jr. Propeller Head
Posts: 7
Joined: Tue May 21, 2013 4:40 pm

Regular importing of Markdown files

Post by JHine »

Hi,
Our company recently took on a new product and we are looking at how best to provide them with online help.
One of the options that has been suggested is keeping their help in GitLab in Markdown files and importing to Flare to produce the output. Sorry if I sound a bit vague, but I've not had any experience with this, which is why I'm asking here for advice.
The developers would prefer to keep everything in GitLab so they have all the information they need in one place (including all developer-only related information). They would also control the content, with GitLab being the only place where changes are made; Flare would only be used as the tool to produce the output (and apply our branding and styles). I believe this information can be shared with customers (but I don't fully understand how this works yet - we're still very much in the early stages and doing our research before deciding on the final course of action).
Does anyone else do this? What are the benefits?
Would appreciate anyone's thoughts on pros and cons of this process.
I know what my preference would be (and that would be to use Flare to author the content :wink: ), but open to other ways of producing help for our product. Also, they have not had a technical writer before so are used to writing their own doco, with help from other members of their team.
Thank you in advance.
trent the thief
Propellus Maximus
Posts: 608
Joined: Wed Feb 01, 2006 6:21 am
Location: Off in the dark....

Re: Regular importing of Markdown files

Post by trent the thief »

Hi,

Being stuck in a gig where they're married to a static site generator is a bad situation.

I've been there and there's no room for two tools. You'll work yourself to death trying to maintain the markdown content in two places. I've found that devs in SSGs tend to start thinking that they can write well and that their writing and layouts are suitable for clients because they've been doing it for so long. On the flipside, some teams are sick of it and really want someone to do all of that for them. I hope you have sick devs. The other kind are a nightmare.

IMHO, an SSG/markdown gig is the very last resort. I'd rather do business analysis work than use an SSG.

Markdown and SSGs form the "Fisher-Price" version of an authoring tool. They are a step backwards to the old days when word processors like XyWrite used a bastardized form of Linotype's markdown to format text. Markdown is a very light-weight language that is light on features and suitable only for a wiki or a very simple doc. There are many flavors of markdown and feature differences. I'm at work so I don't have the time to list all of markdowns shortcomings when used for documentation :roll:

SSGs don't have the concept of "project." Hence, neither do they have project-level tools or reporting. You are responsible for low-level maintenance while authoring. Also, there're no pre-build project metrics or information available as you work as you would find in other authoring tools (Flare has many). SSG's have a raft of issues that most of their adherents (who are primarily devs) think are acceptable, but cause most writers to cry.

Styling is applied manually with codes rather than choosing from a picklist

SSG Themes contain features and CSS Styling. Expect breakages after an SSG or plugin/theme/add-in update caused by the SSG and those features not being synced.

No central support for the SSG and it's required add-ins, plugins, or for whatever flavor of markdown it uses (there are a bunch). If something breaks there are forums to post help request and bugs, but no one is obligated resolve the issue or even investigate for you. I've seen many posts where the feature dev blames the Markdown flavor and recommends posting with the markdown site, and markdown blames it on the theme.

Version mis-matches between features and the SSG cause breakages. Release times vary and features will break regularly as packages update. Many hands without central control. Upstream package vulnerability management - who's watching the security?

If the SSG or theme automatically pulls changes you can end up with a broken project when they update. If you can't change their minds about using an SSG, at the very least, disable automatic ssg/theme/add-in/plug-in updates from git.

Very few OOB features. Whomever is stuck with the SSG maintenance and config must find and implement missing presentation features into the SSG - and keep them running when they break after an update.

If a feature you want is not available in the SSG/Theme combo you're using, you need to implement it. There are thousands of web sources. Good luck finding one that is your combo and still version current. It isn't impossible and with enough research and testing you can puzzle them out. But you won't be doing any writing while that happens (personal experience). Unless you can use an SSG/Theme right out of the box and write with only what they offer, you're going to spend a lot of your time just getting it do what you need it to do in the manner in which you need it done. That eases off eventually, but it's miserable while you're doing that and dealing with people wanting docs yesterday.

Can't link check the source.

Cross-reference and Link building is manual.

No support for pre-built cross-ref formats.

If you update a page title/filename or link you'll need to grep the project to find and update those occurrences, as well. Any changes (whether to the URL or the link text) must be flowed throughout the docset by anyone touching it. That causes problems when a dev updater knows his section, but doesn't realize that their information is in other locations within the docset (a common occurrence exacerbated by large teams).

No support to conditionally exclude items (text/styling/etc.)

Even though it's the slowest and least efficient way to review documentation, many devs think they can treat doc as code and believe that reviewing markdown docs in Git is acceptable. They can quite quickly get caught up in challenging markdown code rather than the content. If it renders the way it supposed to, that's good enough for me. Wait until they start reviewing in Git and complaining because a body text line that renders perfectly did not start in column 0 or some other irrelevant nonsense. That is a nightmare beyond the pain of dealing with the tool.

Extremely poor list handling - No list continuations after needing another paragraph type or image within the list.

In my experience, using an html list is more efficient than a markdown list since I can then add styling to the list (colors/numbering formats/etc.) and add secondary paragraphs, image, code snippets/command line examples within a step.

Table handling is extremely basic- Either typed in manually or created in another tool (trust me, make them in another tool) and then run though an external markdown table maker site. Only very minimal table styling is possible.

Lack of table style options (colors, restricting page breaks inside cells or the table) or easily used options (border weights/types, merged cells)

Can't easily put a list into a table - markdown tables choke on line breaks so you may end up with a solid, couple hundred characters if you need to add a list in a table cell.

When a build fails, the debug output I've seen from three generators was almost useless.
-------------------------------

This is such a rich topic and I'm only sorry that I can't devote the full day to an answer.

Take care, stay safe.
Trent.

Certifiable.

Image

umm...
I meant MAD Certified.

Official Propeller Beanie Owner :-)

:flare: Are you on Flare's Slack channels? PM me for an invitation! :flare:
Psider
Propellus Maximus
Posts: 811
Joined: Wed Jul 06, 2011 1:32 am

Re: Regular importing of Markdown files

Post by Psider »

If there was a "like" button in this forum, I'd use it for your post Trent. Thanks very much.
trent the thief
Propellus Maximus
Posts: 608
Joined: Wed Feb 01, 2006 6:21 am
Location: Off in the dark....

Re: Regular importing of Markdown files

Post by trent the thief »

There are tools beyond pandoc for working with markdown content. I started using Mattias Sander's Kaizen plugin this morning. I'm 80% done with a long word import I'd blocked out for 20 hours. Five hours work with the plugin put me more than a day ahead of schedule.

He has a dedicated plugin for Markdown that might be a last hope if your team is dead set on using markdown files. The webinar discusses using that as an intermediate step between devs and Flare. They still get to use markdown, and hopefully you'd be able to use Flare.

The below link demos Kaizen, but has some info at the end about the other plugins.
https://www.madcapsoftware.com/webinars ... zen-plugin
Trent.

Certifiable.

Image

umm...
I meant MAD Certified.

Official Propeller Beanie Owner :-)

:flare: Are you on Flare's Slack channels? PM me for an invitation! :flare:
Nita Beck
Senior Propellus Maximus
Posts: 3667
Joined: Thu Feb 02, 2006 9:57 am
Location: Pittsford, NY

Re: Regular importing of Markdown files

Post by Nita Beck »

I have no experience with this myself so can't comment on how good the results might be, but Flare 2023 (not sure of earlier versions) can import Markdown directly. See https://help.madcapsoftware.com/flare20 ... rkdown.htm
Nita
Image
RETIRED, but still fond of all the Flare friends I've made. See you around now and then!
trent the thief
Propellus Maximus
Posts: 608
Joined: Wed Feb 01, 2006 6:21 am
Location: Off in the dark....

Re: Regular importing of Markdown files

Post by trent the thief »

I haven't tried importing in 2023. The issue isn't so much that Flare doesn't know what to do with a markdown file, but rather how to it handles an SSG project import.

Flare pulls in the files and depending on which SSG and markdown it's using, you end up with an index or _index file in every directory, broken links, circular CSS references, broken links, and possibly lost content from processing their shortcodes (i.e., feature/layout constructs that mimic feature real authoring app use).

If one has a workflow where devs work in markdown and the author works in flare, using pandoc or kaizen would do the trick. I'd pick kaizen, for sure after using it for a couple days. I'm definitely loving that plugin.
Trent.

Certifiable.

Image

umm...
I meant MAD Certified.

Official Propeller Beanie Owner :-)

:flare: Are you on Flare's Slack channels? PM me for an invitation! :flare:
Post Reply