A note on the philosophy of the webkit and its documentation

[alberto]

@owen and @hugi, thanks for this.

I am now done with iteration 1 of Webkit Usage. There is still some information missing: I have @mentioned you to mark the points where I need you to fill it in. Once everything is in place, we can upgrade it to manual, with @matthias’s permission.

When making a website with the webkit, the main tool at the layman’s disposal is the example configuration file, or rather configuration post. I already recommended spending some care making one with example code for all the types of content supported. Now I want to add another recommendation: be generous with inline comments:

<!-- XML comment here -->

Problem with that, of course, is that an XML tag is not rendered by Discourse. We can live with it, and I already added it to the guide:

@alberto

General principle: you need to edit the configuration post in order to see all elements of it . This because Discourse hides some elements, including XML tags. So, don’t worry if the configuration post does not look right: edit it, then look at it in the edit window, and everything will be there.

That said, if anyone is aware of a better workflow, incorporate it in the guide.