It's a known problem in the software development world that documentation tends to get stale. In some projects lots of things are very poorly documented. This is also true for the Imba project. There is a lot of amazing hidden features that are not obvious and invisible to you unless someone tells you about it. Few people actually sit down, read the internal implementation and learn how to use it.
The Current State
As of this writing, we have an outdated imba.io website. The examples there apply to the stable v1.5.x branch. Since development is mostly happening on the unreleased 2.0.x, imba.io is not going to see any changes soon.
The navigation link to the docs is actually more of an API reference. Finding stuff is hard since there is no search. You have to resort to using a search engine. To avoid dwelling on the negative bits, let's look at some of the positive things.
Since imba.io is written in Imba we do have support for syntax highlighting and running snippets. Also some cool things are down with Markdown in there and the project itself is actually pretty neat with the way code is compiled and run on the client-side. Nonetheless, this was all a hassle to maintain and at times made it unnecessarily hard for new contributors to get the site running locally.
How to Make it Suck Less
The way we are going to tackle this issue in the Imba project is in a couple of ways.
i) Content is King 👑
First, we have decided to focus on the content and not how it's being rendered on screen. This means that instead of spending lots of time in building a own tool for writing documentation we will be using GitBook.
GitBook is a web app for editing and synchronizing your docs. It works with existing GitHub repositories. We have connected it to a subdomain docs.imba.io. This again lets us focus on the user. We can spend time on the actual content you will be reading instead of the invisible bits.
ii) Outline the Documentation
Before we start writing lots of pages. We will have sketched out groupings and main titles. This means that we will be spending much more time on thinking about better ways to present Imba to the reader.
ii) Looking at the Competition
We will definitely be looking closer at projects like Vue.js, Svelte, Preact.js and many more for ideas on how to better present concepts / syntax.
Thank you for reading! I'm Alexander, Web Developer at Scrimba - The mind blowing way to learn how to code.
Top comments (0)