Preparing for the next release of Animation Nodes, we decided to rework the documentation. In this post, I shall outline what we are trying to do, what we already did, and what we need to do in the coming weeks.
Migration
We migrated the documentation from Sphinx/ReadTheDocs to Hugo. There are many reasons why we think Hugo is better than Sphinx/ReadTheDocs, some of those reasons are as follows.
- Performance. Hugo can build the whole documentation in less than 2 seconds, from scratch, yes, that's 100x faster than Sphinx.
- No dependencies. Hugo is a binary with no dependencies whatsoever. You don't need to install a python runtime, you don't need extra modules, you don't need anything special, just install and build. This should reduce the barrier for contributions.
- Live Reloading. Hugo builds and reloads pages on the fly, so it is more friendly to use.
- CommonMark. We use the standard commonmark markdown markup language. We no longer have to deal with the complexity of RST.
- Extensibility. We can extend the documentation using Go's templating functionality, which is rather easy to use and is well documented.
The documentation was also migrated to Animation Nodes's web server, and it will be available at https://docs.animation-nodes.com/.
Content
Organization
The structure of the documentation changed into leaf pages with some category branch pages. Leaf pages allow each page to have its resources self contained, which will make it easier to track, add, and refactor. Branch pages usually represents categories and should generally list their children. The following figure demonstrates the new structure.
|-documentation
| |-subprograms
| | |-_index.md
| | |-invoke
| | | |-index.md
| | | |-one_time_cache.png
| | | |-once_per_frame_cache.mp4
| | | |-once_per_input_cache.mp4
| | | |-change_subprogram.png
| | |-expression
| | | |-index.md
| | | |-expression_node.png
| | | |-expression_node_example_1.png
| | |-group
| | | |-index.md
| | | |-network_error.png
| | | |-group_example_2.png
| | | |-group_example_1.png
| | | |-invoke_example_1.png
...
We have three leaf pages (index.md
) and one branch page (_index.md
). Each page have its own resources next to it.
Media
We converted all gifs into H264 videos in mp4 containers. We will no longer allow gifs in the documentation. In most cases gifs are of inferior quality and of much higher size. The videos are, of course, inlined and autoplayed, so the user shouldn't notice any difference, aside from the faster load times. Videos are added using the video
shortcode as follows.
{{< video an_example_video.mp4 >}}
Front Matter
Pages needs to have a Front Matter that describe its contents. We can write the front matter in YAML, TOML, or JSON. Our choice for the front matter format is YAML, but most pages only have one or two simple YAML statements as shown in the following front matter, so this shouldn't be a problem to those unfamiliar with YAML.
title : Example Page Title
chapter : true
Issues
Deployment
Currently, we deploy the documentation using the lftp
FTP client. The problem is, it takes about 30 minutes to deploy the website, as it uploads everything, not just the changes. It is unclear to me if this is something we can solve somehow, but we definitely need to find a better way to handle deployment.
Automatic Migration
The content was migrated mostly automatically, so we expect there to be bad content which we will have to iron out manually.
Page Order
Currently, pages are ordered by their weight, a value that is defined in the front matter. This is bad because if we want to add a page in the middle, all pages after it will be have to be updated.
Practical Documentation
The Problem
The main problem we have with the documentation is that it is not practical, it nothing more than a mere reference in most cases. Even the examples provides are superfluous and are more of a demonstration than an actual practical example. Asking developers and documentation writers to provide more practical examples is ... not practical. Can you think of a practical example for a node that returns the maximum number in a number list? You see what I mean?
The Proposed Solution
Multiple users pointed to me that my answers on StackExchange were far more useful than the official documentation. That's why I mostly concerned myself with helping users on StackExchange than improve the documentation, but that was before I left StackExchange.
That's why I am proposing a new way of writing practical documentation for Animation Nodes. First, the Example Of Usage section of nodes will be removed. Instead, a new section that only contains references to "Example Pages" will be added. An example page is a page that follows a tutorial like structure, where the author describe how to reproduce a certain setup in Animation Nodes. An example is not related to a particular node, it only occasionally use the nodes that references it.
But how do we populate those examples? The example page will be populated in a Q&A manner. Users can ask questions here on this repository, on StackExchange, or in any other network. Once the question is answered, the answer can be promoted into an Example Page or it can be used to improve a certain documentation page. #56 is one such question that can receive an answer than can improve the documentation.
The Q&A style documentation writing ease the burden from the documentation writer and makes a stronger connection with the end-user.