Register a SA Forums Account here!
JOINING THE SA FORUMS WILL REMOVE THIS BIG AD, THE ANNOYING UNDERLINED ADS, AND STUPID INTERSTITIAL ADS!!!

You can: log in, read the tech support FAQ, or request your lost password. This dumb message (and those ads) will appear on every screen until you register! Get rid of this crap by registering your own SA Forums Account and joining roughly 150,000 Goons, for the one-time price of $9.95! We charge money because it costs us money per month for bills, and since we don't believe in showing ads to our users, we try to make the money back through forum registrations.
 
  • Locked thread
nem
Jan 4, 2003

panel.dev
apnscp: cPanel evolved
I'm undertaking documenting our entire panel from installation to third-party API integration. What documentation software exists that supports:

  • Markdown (easy version control)
  • Table of contents
  • Templates, styling common components e.g. inlining code, terminal commands, and asides
  • Syntax highlighting would be nice

I'm using Dillinger, but beginning to realize how woefully insufficient this will become as documentation grows. Alternatives like Readme sound great a few years down the road, but right now it's just me writing docs. Docs ship with releases, so I'd like to bundle code commits with doc changes making Markdown suitable over HTML. Going that route also rules out a wiki.

The project covers PHP, JavaScript, bash, MySQL, PostgreSQL, C, and a variety of configuration file formats. Is there anything that hits the requirements above and produces a layout similar to RedHat's documentation system?

Adbot
ADBOT LOVES YOU

nem
Jan 4, 2003

panel.dev
apnscp: cPanel evolved
Bump for those curious:

Ended up going with Markdown instead of reStructuredText for documentation and building the docs as a Jekyll site using Bootstrap's approach as a boilerplate. Using Typora to write out the docs on desktop or laptop and committing to a git repo; it's perfect.

MononcQc
May 29, 2007

For some of the open source tools I maintain, we've been using readme.io. It's alright, but their have custom extensions to markdown that only work with Javascript and basically all the exports of the docs you write in there are incompatible with any existing software but theirs.

I've started using gitbook for some notes I'm organizing in a book for property based testing and I settled on their asciidoc support and so far I'm finding it pleasant aside from some javascript stupidity in their stack.

Scaramouche
Mar 26, 2001

SPACE FACE! SPACE FACE!

When I was doing big boy tech writing (e.g. 3000 pages ISO 9001 crap) we used Adobe FrameMaker and it was frankly terrible.

gay for gacha
Dec 22, 2006

I've been using Emacs Mark-down mode and eww in another tiled window to do some on the fly markdown doc writing. Do you guys have any resources for writing good documentation?

Adbot
ADBOT LOVES YOU

EssOEss
Oct 23, 2006
128-bit approved
It is not quite clear what exactly you want. Do you want something like Word that does all that? Or do you want to generate output that uses all that?

I use DocFX - it generates neat structured websites from markdown files, code files, images and everything else I wish to throw at it. Works great for all my needs.

  • Locked thread