Using Flare for Modern Developer Documentation

[iand]

Hi,
I've been asked to recommend a tool to create developer documentation (getting started guides for programmers) with lots of code samples. The model is https://stripe.com/docs or https://www.algolia.com/doc/ruby#using-the-api i.e. frameless with side navigation. Note this is not for API reference as we are using a separate tool for that. I will use prism.js for syntax highlighting. The main criteria from management is that the site should look modern and attractive.

Does anyone have experience creating this kind of HTML5 output in Flare? I am an experienced Flare user but have not previously hacked the output to quite this extent. Is Flare a good option here (Pdf is not required) or would a static site tool e.g. Markdown and Jekyll, ReST (Sphinx), or Asciidocs be a better idea? Markdown seems a bit limited for serious technical documentation due to the lack of conditional text, variables, etc

I guess this could be achieved using frameless HTML5 output without a skin ideally using a responsive framework such as http://foundation.zurb.com/. I could set up a script to run after each build to process the TOCs for all the developer guides and create the side navigation panel. Has anyone had success with such an approach?

I suppose search could be implemented using Algolia or Swifttype or similar.

Thanks for your help
Ian

[Msquared]

Hi there,

I've just spotted this post. DId you find a solution, and if so, what did you go for? I find myself with a similar requirement.

regards

Marjorie

[ecjoe]

Hi,

I am also very interested in hearing about your developer documentation implementation.

[wouter]

Are you aiming for 'living' documentation, which is collaboratively written and maintained by you and the developers? Then I would not recommend Flare. It will be way too much of a hassle for the devs to add or modify content (without your intervention), and they'll end up just not doing it. You're better off with something like Confluence, Nuclino, or one of the static site engines you mentioned.

If your aim is autonomy and control, i.e. you want to be able to create, edit, organize, style and publish content without much help from others, then Flare might be a good option for you. But it's either/or, I'm afraid.

[Dee Vincent-Day]

I use Flare for Customer Facing documentation and we use markdown for developer docs.

our docs as code solution is to store the markdown in a git repository with Jekyll to build and publish the static website. I have not had to set up the Jekyll, this is the job of our developers.

To edit the Markdown I am using VScode with plugins. The plugins provide support for GFM (git flavour markdown), English Language grammar checking and YAML support.

We also use Liquid commands to add functionality similar to snippets in Flare (known as includes) and to use a jekyll plugin to format notes and warnings (known as alerts).

I have a plugin that allows me to import markdown into Flare but I cannot export it out again. The plugin converts the markdown to HTML. This plugin is available here:

http://www.kaizenplugin.com/

This plugin is developed by Mattias Sander and he welcomes feedback.

I also use other features available with this plugin. I have found the ToDo list method extremely useful.

I know a lot of developers favour Sphinx and asciidocs over markdown. This post explains why:

http://ericholscher.com/blog/2016/mar/1 ... nical-docs

If you can install Slack there is a great slack team for Flare and another called Write the Docs. In then Write the Docs there is a Channel dedicated to Flare and another channel titled Docs as Code. You can ask lots of questions in there.

[Dee Vincent-Day]

If you wish to receive an invitation to the Flare and Write the Docs Slack Groups send me your email by direct message and I will generate an invite.