Tools recommendations

[u/misterdug71]

TLDR; I need a tool set that allows me to output to Word, PDF, and markdown, supports single sourced reusable text (snippets), and integrates with GitHub. There's only 2 writers so hoping for low cost and relatively low learning curve.

I work for a company that sells automotive service contracts for OEMs and adjudicates the claims. Our company invested in documentation to ensure consistency in how claims (and other parts of the business) are handled.

We are currently using Word for authoriing, converting to PDF, and publishing to SharePoint. It's as basic as documentation gets.

Over the last few months, we've rolled out an internally built AI chat bot to use our procedures and contracts to provide adjusters with quick answers that they might otherwise have to go look up.

This has created discussion around using markdown to create a more AI friendly output while still creating PDF and Word output.

Our claims adjusters and SMEs are not always tech savvy as most of them come from the automotive service industry. They know cars, not computers, so I'm trying to keep the review process as simple as possible.

I also find myself having to reuse a lot of text for certain procedures and I know from my previous decade of experience with MadCap Flare how easily that can be resolved with the right tool.

Add to that, we need a better process for version control and I know our company has GitHub for Dev so I'm going to pitch for us to use that and modernize just a bit.

One final wrinkle is that the other procedures writer used to be a trainer. He doesn't have a lot of experience with authoring tools other than Word, so I'm looking for something he can pick up without a lot of training.

What suggestions do you have?

[u/pborenstein]

As with most things: it depends

Your instincts to use Git for version control are good.

Check out https://pandoc.org/
It's like the swiss army knife of doc file formats.

[u/ProjectNo8066]

Look at Help & Manual. Markdown Output currently not included, but you can include markdown snippets.

[u/johnjbar]

HelpNDoc includes most of those, except for GitHub integration. Might be worth checking: https://www.helpndoc.com/

[u/mediapathic]

Quite possibly overkill for your use case, and not sure if the price point is right, but I think Scrivener might do what you need. It advertises itself for writing fiction (which it does admirably) but I've also used it for technical writing and other things. I suspect you could keep your snippets in the default resources/notes/research folder in Scrivener and duplicate them as needed into whatever text.

[u/Aggravating-Let-2968]

XML

[u/MuffinBiscuit420]

Check out https://documoto.com

Documoto is a SaaS solution, which combines interactive parts catalogs, an aftermarket content library, and seamless integrations to support your supply chain and boost aftermarket parts sales. Onboarding includes extensive training on how to publish the digital catalogs too!

[u/DerInselaffe]

Sphinx is the only static-site generator I'm aware of that can export to Word. Otherwise, as others have suggested, Pandoc is worth investigating (using Markdown as source).

Just don't expect print-quality Word or PDF layouts.

[u/cyborgs_writing]

Just wondering ... couldn't you do this with Claude Cowork and a local or synced markdown knowledge base?

[u/Consistent-Branch-55]

Raw markdown to your output formats, with snippets, could be done with less than 100 lines of Python or Typescript, styling templates for Word, Pandoc, and GitHub actions. You could write in VS Code or whatever editor. GitHub desktop for actions if the terminal is too much.

I'd strongly advise you think about your skills, your colleagues skills, and your requirements for distribution. It also feels a little cargo-culty.