I write a lot of tools for 3dsMax. Some are small and easy and some are big and complex. But what I always try to do is to write good documentation for them. This tutorial is not about how to write but how to make it easy to get solid docs up and running.
Waste of time
Writing documentation is a waste of time. That’s how I felt for a long time. But I’ve learned that it’s quite the opposite. First of all, good documentation helps users find their way and means less support through email (saving me time). Writing documentation also forces me to look at my own software from a different perspective. It happens often that after writing documentation I go back to a feature because I notice it’s too complex or badly designed.
Sphinx
Currently I’m using Sphinx exclusively to write documentation for my 3dsMax tools. Sphinx is a python module and lets you write documentation in a format called “restructured text”. It’s similar to markdown but with a few extra bells and whistles I actually use. It helps you to create a table of contents, link within the documentation and add images, videos and so on.
Summary
I’ll summarize here what you need to do to get going:
- Install python, sphinx and the Read-the-Docs theme for sphinx
- Run the sphinx quickstart. It sets up your first project
- Start writing your documentation
- For good order: publish the docs to github pages for free hosting and version control
This really gives you a super solid documentation pipeline. It takes a bit of time to set up but once that’s done, you’ll be churning out docs like no other!
The tutorial
I’ve written the actual tutorial with Sphinx and embedded it here. You can also check it out on github pages or got directly to the source on github.