We took the arguably uncommon option to construct a desktop app for documentation. For those who go searching, documentation instruments typically fall in 2 classes: open supply CLI instruments, and cloud-based WYSIWYG editors. On this publish we’ll speak concerning the reasoning that lead us to construct a desktop app as an alternative, and the way it truly works.
What’s it for?
Our desktop app permits customers to preview what their documentation will appear to be as soon as revealed. It additionally catches errors equivalent to damaged hyperlinks or syntactical issues.
Customers can open our app subsequent to their editor of alternative, edit their Markdown paperwork, and the app will refresh on each save to replicate the most recent model.
When an error is detected, the person is instantly notified, and clicking on the hyperlink within the error takes you to the web page with the difficulty.
Whereas my opinion is clearly biased, this quick suggestions loop is wonderful to work in. It takes the app milliseconds to do a whole re-render of the venture, so that you’re capable of transfer basically as quick as you kind.
Why a desktop app?
Doctave is constructed with
docs-as-code
in thoughts. As mentioned above, there are two fashionable approaches for documentation instruments: CLIs and cloud-based WYSIWYG editors. The purpose of docs-as-code is engaged on native information in supply management so the cloud was out instantly.
So this leaves the CLI choice. There’s nothing “technically” that might have stopped Doctave from having this interface:
$ doctave serve .
Serving your docs at http://localhost:9090
...
However listed below are the negatives for requiring a CLI.
Higher UX
There was a resurgence of desktop functions prior to now few years. That is doubtless partly on account of applied sciences like Electron making it simpler to ship functions constructed with net applied sciences as cross-platform desktop apps, but it surely’s additionally arguably
as a result of the person expertise may be higher.
Our customers love that the preview and error checking occur in a single place. You do not have to spin up terminal periods and swap between an editor, a terminal, and a browser.
Additionally, our app is quick. We’re utilizing Tauri for the shell of our app and the enterprise logic that compiles your documentation is written in Rust. It runs natively inside Tauri, and never within the browser atmosphere (extra on this beneath). That is how we are able to get such quick response instances: we run native code as an alternative of a bundle of JavaScript and even WebAssembly. Would it not be attainable to do that in a CLI? Sure, however the desktop app offers us an excellent atmosphere to take benefit each native code and net applied sciences.
Lastly, updates turn out to be trivial. Tauri’s built-in replace operate has labored flawlessly, throughout 3 working methods, making certain our customers have the most recent and biggest model with minimal headache. You get a pop-up each time there is a new model, and the replace occurs routinely. There is not actually a common approach to replace CLIs.
Non-developer customers
Lots of people working with technical documentation usually are not builders themselves. They’re nonetheless technical, however in roles like tech writers, product managers, or help brokers. They’re snug on the command line, can use Git, however don’t wish to spend time understanding why their model of OpenSSL doesn’t match what is predicted.
In case you are anticipating your customers to setup a posh improvement atmosphere to run your device, you might be alienating this vital group of customers. Even builders get annoyed when small atmosphere variations trigger npm set up to fail!
There are methods to mitigate this, equivalent to constructing static binaries. However you continue to have the issue of getting your customers to replace your SDK once you launch options, you must help totally different package deal managers, you must ensure that your software program shouldn’t be flagged by the OS as malicious, and far more.
A typical remark we hear from our customers: it is simply simpler to make use of Doctave.
How does it work?
As talked about above, Doctave makes use of Tauri because the shell of our utility. Consider it as a light-weight and security-focused Electron. It is a very fascinating venture that I extremely advocate testing. For our functions, listed below are the two key options which might be fascinating:
- It makes use of every working system’s native net view, making app bundles
considerably smaller - You possibly can code your native “backend” in Rust which you’ll be able to invoke from inside
the net view
(NOTE: this isn’t a “net server backend”. That is code operating natively
contained in the native Tauri course of.)
Doctave’s core documentation venture parsing code is written in Rust and we name it libdoctave. It takes as enter a bunch of information and creates an in-memory construction that you need to use to render a Doctave documentation web site. It’s used each within the desktop app and on our net platform, written in Elixir, through Rustler.
That is how we’re capable of share code throughout the desktop and the net platform. We will render the identical content material identically no matter the place we’re.
Rendering a web page
For example, let’s stroll via what occurs when Doctave renders a web page you might be modifying.
First, Doctave is operating a thread inside our native “backend” that’s monitoring filesystem occasions. If it detects a change, it triggers a refresh of the venture. Here is how that works:
- The backend re-reads all the venture information from disk
- It feeds these information to
libdoctaveto create an in-memory illustration of the venture -
libdoctavefirst runs aconstructstage, to examine the venture is syntactically right -
libdoctavesubsequent runs aconfirmstage, the place all pages are checked for points - Lastly, the requested web page’s HTML is serialized and despatched to the frontend to show, together with any errors
This all occurs in single-digit milliseconds each time you edit a file.
As you’ll be able to see, there may be nonetheless a number of room for optimization if ever required. We could possibly be smarter about incrementally updating the libdoctave in-memory illustration. We might cut back IO by solely studying the information which have modified.
To this point, nonetheless, that has not been essential.
Desktop apps rock 🤘
Betting on Tauri and having a desktop app basically has been an excellent resolution. Particularly with our selections of applied sciences, specifically Rust, this mix has been a pleasant if considerably unconventional tech stack.
Each startup has a sure variety of “innovation tokens” that you need to use on dangerous and/or new applied sciences. In our case, this was an excellent funding.