Documentation

[fredck]

This is a summary of ideas and requirements for the CKEditor 5 documentation project.

Target

• Quick drop-in developers
• Custom solution developers
• Non-developers (end users, managers, researchers, social)

  Delivery

A single website containing the following main sections:

• Samples: a title with optional description followed by a demo with a JSFiddle link.
• API: documentation extracted from source code.
• Articles: advanced documentation about concepts, architecture, etc.

  Software

It may happen that different software solutions will be used to produce the different kinds of documentation predicted. The following are basic requirements:

• All different parts are seamlessly integrated in the navigation of the docs site.
• All sections have the same UI styles and look like a single unit.
• Linking among the different sections must be easy and intuitive.
• All software tools must run on Node.js.
• There must be the possibility to have offline copies of the documentation.

  Source Documentation

• The source documentation will be present within the repositories that contain CKEditor 5 code. Core repos as well as plugins will have their own documentation, which will be then unified on documentation build. This must allow for custom plugins to be as well documented.
• There must be ways for linking to documentation between different repos. For example, from a plugin to core or even to a plugin it depends on.
• Generic samples and documentation and the documentation core project will be located at the ckeditor5 repo. (We may decide to have ckeditor5-docs instead)
• Each repo should organize the documentation in a standard directory structure to be defined.

  Samples

• They should have little text or, even better, zero text.
• They are made of source code which is used for two scopes:
  • Demo the sample inside the documentation.
  • Showcase the sample in JSFiddle.
• Samples can have their own tests, to guarantee that the changes in the API are not breaking the samples.
• Some samples may be marked as PoC (Labs!) though showcasing (far-from-been-production) prototypes, similar to the ones we had during the hackaton.

  Building

Specific gulp tasks should be available to build the documentation site. Hopefully relative linking will be enforced so the documentation is navigable locally.

Varia

• The solution should be SEO friendly and accessible.
• The builder should be able to validate links so we can ensure integrity of the documentation. API docs links can be even checked by project’s linter.
• The builder can be developed in a generalized manner (unless that’d slow us down too much), becoming an interesting open source project for documenting JS projects.
• https://github.com/cksource/samples-framework could be used for theming the project.
• A project version picker would be a nice feature (that would need to be a special builder option to build documentation for all tags in ckeditor5).
• Since we’re considering extracting CKEditor dev tools (i.e. builder, dev tasks, etc.) to a separate repository, perhaps that should be done first.
• We'd like to have comments on all pages. Some external service like Disqus would need to be used.
• We need code samples also in guides. We need to decide whether we want to make all code samples "live" or just some. And whether "live" should always be done by using JSFiddle or not.

[Reinmar]

More varia stuff:

• We'd like to have comments on all pages. Some external service like Disqus would need to be used.
• We need code samples also in guides. We need to decide whether we want to make all code samples "live" or just some. And whether "live" should always be done by using JSFiddle or not.

[fredck]

@Reinmar: Amended "Varia" with your suggestions.

[Reinmar]

We've been talking with @fredck about releasing CKEditor 5. The biggest cost of releasing CKE 4 is ensuring that there are no broken samples. There's a huge test suite for the code which helped us catching nearly all regressions, but we didn't have anything for samples.

CKEditor 5 samples will be used in at least 2 critical places: its website and in the documentation (which consists of samples and other code listings). Possibly, also in other places, like a sample shipped in some packages (if we'll keep those).

With time the number of samples may grow high above CKE 4's, because coding features for CKE 5 is much easier. We clearly need to automate the process of testing them.

Initially, we thought about a repository with CKE 5's samples, which we'd simply test using Bender. Each sample would have an HTML, JS and test files. Then, the documentation would use all those samples and also the website would include some samples directly from this repository.

I'm afraid though, that we oversimplified this. There are couple of things that we need to consider:

1. Each sample may require a different build of CKEditor. Additionally, on production they may be loaded from a CDN, and of course they will be bundled. Hence, running tests on a dev version of CKEditor makes no sense. We'll need to figure out a way to run tests on a specific kind of packages. We'll also need to understand how many different builds we should produce to ensure good performance of our websites.
2. CKEditor 5 packages will bring their own samples, so there will be no centralised repo with them. Ha! That's amazing for one, but means that each package should test its own samples first. But then how to test them with specific package types?

PS. As for shipping CKEditor bundles with at least one sample, that's tricky too... Specific project configurations (like – I want these Editor classes and couple of random features) means that there's nothing we can be sure. Definitely, the only type of packages which actually know how to create a sample are those which contain Editor classes, so that could be the starting point for us. But since you can have many of those in certain types of bundles, I'm really worried about running all that. I'd rather resign from having any samples in bundles. Let's have them in the documentation. Also, people were complaining that we're shipping bigger packages than needed, which makes some sense as well.

[fredck]

I'd rather resign from having any samples in bundles. Let's have them in the documentation.

+1

I think it is better to have a single place with all samples.

[Reinmar]

@postJScriptum sent me a link to http://redux.js.org/ which is built on https://www.gitbook.com/. We won't be able to use the engine, but I like the Redux docs very much so we can get some ideas from it.

[Reinmar]

When we've been talking with @wojtekidd about what CKEditor 5 is ("a framework with ready-to-use solutions build on top of it") we independently started thinking about the structure of documentation. The idea is to split documentation into two main use cases "framework" and "solutions". This can still be one page, but its structure could be defined by these two categories.

I think this is an interesting idea. Those two groups of developers have very different needs and following this convention we may be able to create two sites where none of them will be overloaded with partially useless stuff. Especially for the group looking for ready-to-use solution this will be a better experience, because the documentation will not be that overwhelming.

WDYT?

[Reinmar]

Cleaning up old discussions. See https://github.com/ckeditor/ckeditor5-design/issues/186.