Developer docs

[mlewand]

We need to think about dev docs - how do we want generate them etc.

Because we're unlikely to publish API docs inside CKEditor API docs.

[fredck]

I confirm that we should not have it inside CKEditor docs. We need a dedicated docs site.

We should use the same strategy as CKEditor though, with JSDuck.

[AnnaTomanek]

I will play devil's advocate here. I actually think the developer documentation should be available in standard CKEditor developer documentation, for the following reasons:

• To simply promote this product. Even if we want to concentrate on licensed versions and direct sales, we are still planning some external campaigns to promote it, so it will be talked about in the Internet. It will be strange to simply not have it covered in our own resources. The more people know about it, the more references can be used to send potential customers to the product page, the more we can sell?
• For PR reasons: If we keep it separate, hidden, it will be looking a bit shady, as if we forgot about our mission and values. It's totally OK for an OS project to have paid addons but it looks strange if suddenly we are trying to be secret about them. We've always been open about what we do, for free and for money, why change it?
• People using the product will need support. Especially if they paid for it. It won't be comfortable if they need to research a11ychecker configuration options and how to change editor configuration and how to change toolbar buttons in separate places. If they come back to their CKEditor configuration in a while, they will probably start looking at the official docs first and will get a WTF feeling, not remembering about the separate a11ychecker resources. Frustrating customers is probably what we want to avoid...
• Separate a11ychecker documentation page is yet another place to maintain and will look a bit poor, with a full-blown doc site template and very little content. We would need to repeat some of the information from the CKEditor docs as well to avoid sending people there all the time.
• Last but not least, we finally have really good documentation+samples, with emphasis on editor features that we want to promote and showcase. It'd be a pity to simply not have one of the greatest, most brilliant CKEditor features that we will be so proud about there...

Proposed Solution

• We created the special "requirements" box that is used in the docs and SDK for exactly this purpose: to inform the reader about any additional requirements that the described feature needs. This can be information about a particular version required, particular optional plugin needed, third-party component, anything. Examples: http://docs.ckeditor.com/#!/guide/dev_spellcheck, http://docs.ckeditor.com/#!/guide/dev_codesnippet, http://sdk.ckeditor.com/samples/spellchecker.html

My suggestion is to create the documentation and SDK sample just like we normally would, and simply include whatever disclaimer we want. We have this e.g. for the spell checker plugins, with another box and a link to our sales page where the commercial version can be purchased. And even though some SCAYT/spell checker options are only available in the commercial versions, they are still listed on our config page!

In this way the users will be well-informed, we can promote the product as much as we want, good and consistent documentation resources will be a strong sales advantage and all I can see is profit :)

Of course I am aware this is more of a strategic decision and I'll proceed however you want, but these were just my 2c (or rather, 2222c) ;)

[fredck]

Anna, you plan is acceptable, even if I'm not a big fan of this approach.

I always had problems on overly promoting commercial stuff from CKSource in the OSS side of CKEditor. It's like saying that others should also have the rights to do PRs to our documentation repo, adding their commercial products there as well.

I don't want to be a decision maker in this point, but I think it is important for us to not forget about this.

[AnnaTomanek]

Good to hear, Fred, and like I said, I am aware this needs careful consideration.

So far, we haven't had ONE request to add third-party commercial stuff to our documentation. We have the addons repository, and we accept commercial addons there which is huge, we let them make money, add links to their demos and docs, no one has ever wanted anything more than that.

We don't really have any PRs for our docs at all, by the way. Not many people feel like writing docs in general.

Note that we don't need to try to be too intrusive at all, one mention that this needs an additional plugin, one link to CKSource.com and intelligent people will be able to find it. And we can go on and praise this feature as naturally as we would do it for any other great editor feature.

Note that with CKFinder 3 released we will also have the CKEditor docs updated finally (they really need a refresh), and this is a 100% commercial product. We've never made it a secret.

[fredck]

What I said is not based on real PR cases but it is all about the influence that it has on outsiders' perception.... it's to avoid feelings like: "Yes, yes... Open Source... but then the nice features in the docs always send you to commercial stuff out of the project... you're ripping me off!".

I still don't like it... after all, someone must take care of the Open Source side of our project ;)

[AnnaTomanek]

I get this. But isn't it a matter of balance? If we have 2 out of 100 features as paid optional addons, and they are treated most naturally, just like all others, and we are fair and open about what they are then I think the overall perception is better than if we try to hide something.

And support is support. It's only good for us that we document the free features and the paid features with as much care and attention. See, there are always two sides of the same coin, it's up to us how we sell it :) We went really far being open and fair thanks to your policy right from the start, and I think if we still believe in it, there's no reason to change it.

[Reinmar]

My main concern would be how a11ychecker's API docs will look like. If we include CKEditor API docs in them, then we'll have problems with stuff like SEO because of the content duplication. If we don't include CKEditor API docs, then we can't easily link between those a11yc's and CKE's docs, we can't document config options in the same way we do and many other problems may arise.

On the other hand I totally understand Fred's concerns. We don't have currently many commercial additions for CKEditor, but we may have in the future. Merging all them into the CKE's official docs would bloat them even further and will also be confusing and uncool for an OSS project. But separating them will be a pain because we will lose ability to integrate them (linking, linking, linking, referencing types, extending existing CKE's namespaces). It means that we will have to keep the external project's documentation much simpler and it may not be that bad unless the external project shares a lot of APIs with CKEditor ;/.

Perhaps a solution would be to ship every external project's docs integrated with CKE's docs but inaccessible for the crawlers (to avoid SEO problems and people reaching not the docs they wanted). I mean that our every external project would have its own version of CKE's docs (not that I want to merge all external projects in one ultimate documentation :D). This has its downsides too, because information specific to external projects will not be googlable, but it solves many other issues.