We decided to try something new and different from our usual docs.imade3d.com. Something more conversational, more informational, and easier to follow.
Now, our Awesome Documentation Experiment is ready for criticism. We think it’s way better than the old documentation – easier to navigate, easier to read, and it has an integrated chat. What do you think?
The Story of the Darkness
We have had a tumultuous relationship with our current documentation (docs.imade3d.com). It runs on the same system that powers ifixit.com, called Dozuki, and it has some serious advantages. For one, we think it looks great and that ifixit’s push for better docs and self-repair culture is admirable. They have been supportive of open source projects, and seem to be stand-up guys in general. Thumbs up.
Trouble is, the system is inflexible, and has quite a terrible backend. It’s impossible to bulk-edit guides and for many tasks from re-structuring categories to rewriting intros are so laborious we actually had to develop custom scripts. Even then we mostly failed to build the documentation we always wanted.
And the Warm Light
We have decided to try and use a different system; in parallel with the one we have. One that will be deceptively simple. One that we can control. One that is portable – not locked into a proprietary format – and thus easy to share and adapt for different purposes.
Based on our requirements, we have settled on plain text documentation with a powerful sidebar on every page with embedded images, animations, and videos.
For the documentation nerds out there (Click to Expand)
We like Asciidoc and Restructured Text a lot, but the ubiquity of Markdown is hard to beat. So, in the moment, we are writing in Markdown using Zettlr, VScode and Atom, publishing through Git, and rendering out fancy sidebar on the fly with javascript based Docsify.
… and the first experiments with these kind of docs just went live!
Welcome Codename Awesome Docs
Here’s some features we like. Let us know what do you think. What features or content would You like to see?
Clear Flow
We love the sidebar ❤. You’ll never get lost on a page again. The section you’re in gets automatically highlighted, too.
Moving Images
We think that always moving short animations – like gifs – are often the perfect fit for simple actions. We made them look different so they draw your attention as you quickly scroll.
Integrated Chat
That’s right. You can always use forum.imade3d.com and all its power, but for some the need to set up a forum account gets in the way of asking a quick question. We have added Gitter chat room the the Awesome Docs (use github, gitlab, or twitter account) to make it as easy as possible to ask a question or give feedback.
Link to Headlines
Every headline is a link. This is great to point friends to specific sections.
It’s in Git
We currently have these up on GitHub (Github Pages), meaning it’s easy to collaborate, suggest modifications, or make your own version. (Just keep in mind the Attribution-ShareAlike License.)
Open License
Licensed licensed under a Creative Commons Attribution-ShareAlike 4.0 International License so anyone can remix and adapt for there own purposes or pitch in.
Check it Out
As we recently rolled out our beloved OctoPrint upgrade, we knew we needed to step up in terms of documentation. Now we’re trying to expand the system we made for OctoPrint Installation Guide to other JellyBOX guides.
We think it’s way better than the old documentation – easier to navigate and more informational. What do you think?