Documentation changes

by Ondřej Popelka

Short story

We will gradually split our documentation into three parts:

We will be gradually moving our official content from wiki.keboola.com to help.keboola.com and developers.keboola.com.

Longer story

Why?

We introduced our Wiki in the beginning of 2015; it was a quick solution to create a complex documentation of KBC. Over the time, we were listening to what you like and dislike and finally we started redoing our documentation into something we (and hopefully you as well) will like much more. We would like to solve the following serious problems with the current Wiki:

  • The structure is too deep and labyrinthine.
  • Our official content gets mixed with content from our partners in a confusing way.
  • There is no cut between end-user and developer documentation.
  • The Wiki contains some stuff totally unrelated to KBC.
  • There are not enough guides for newcomers.
  • The documentation is sometimes poorly written.

How?

Help.keboola.com will be our end-user documentation. This will be targeted both on people who use KBC on a daily basis and on newcomers. This part of our documentation will assume that you can click, and possibly (but not necessarily) write some code for SQL/R/Python transformations. We promise not to bother you with awful JSONs and API calls. We would really like to keep this part of the documentation as small as possible and have our UI self-explainable.

Developers.keboola.com will be our technical documentation for developers. This will be targeted on 3rd party developers and for users customizing KBC or programmatically working with it. This part of documentation will assume that you can call our API, you can write JSONs, and you can work with the command line and possibly write some code in an arbitrary language. We promise the documentation to be as brief and matter-of-fact as possible.

Wiki.keboola.com will remain our community site. We won't be supplying content to this site any more. We would like this site to become much more open so that more people can share their thoughts and recipes there. 

Dividing the documentation into three separate parts helps us to solve the above problems. By separating Help and Developers, we can flatten the structure a lot. Help.keboola.com and Developers.keboola.com will be both our official authoritative documentation™. If something is wrong there, it is a bug, our bug. Help and Developers differ in the target audience and they will be still connected, but we want a clear message - once you're on Developers, you can't click yourself through. The content of the wiki should be maintained mainly by our partners and 3rd party developers. This will be a nice place to keep e.g. Gooddata tips, which we surely won't maintain. We also work with outside people on making our texts more accessible to non-developers and generally more readable.

Present

Starting now, we are moving some contents of the wiki to our official documentation; we will link old wiki articles to the new documentation (Help and Developers). We will also link to it from the UI or Apiary documentation. We won't be generally linking to wiki.keboola.com and we won't maintain its contents. We know that this might be annoying to you, so we will move the content in hopefully logical blocks so that you don't have to go back and forth too often. The first block for Developer documentation are Custom extensions for KBC and the first block for Help is Tutorial. Once all our content is removed from the wiki, we'll see how its structure can be changed. Meanwhile let us know if you think that there is something we should definitely avoid, or something we should definitely do in the new docs.