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
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.
), 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.
Are you on Flare's Slack channels? PM me for an invitation!