This is only some feedback and a suggestion: making documentation the top “feature” of 2.4.
Currently I’d say Kirby has good documentation, with a few pain points.
Mostly readable and easy to navigate, but I find Cheat Sheet pages hard to navigate.
The Cheat Sheet is my main tool for working with Kirby but it’s downplayed on the documentation home. Also it’s called Cheat Sheet which suggests a very shallow depth of information (programming cheat sheets are often on A4 page), but it’s more like a reference.
Maybe advertising the main documentation contents as a “Guide”, the Cheat sheet (or other name) and Toolkit sections as a “Reference”? Then in detail pages, it’s easy to ignore the right-side navigation; the 3 navigation needs I often have when on a method’s page are:
- Return to Cheat Sheet section (e.g. the
$pagesection when reading about
$page->children. Currently it’s nondescript link at the end of the right column, whose icon is a down arrow (what?). I wouldn’t mind a breadcrumb-like link in the title but that’s me.
- Access other methods in the current section (the previous and next ones alphabetically are not useful). If a full list can’t be done because it’s too noisy, a more prominent link to the section should be enough and the prev/next links should be removed to limit noise.
- Go to the docs for related methods, that do the same thing with a different kind of object (
$pages->children), and maybe hand-picked “see also” methods.
I don’t use the Panel much so I don’t have developer or editor-level issues with the documentation. As a developer (with limited PHP knowledge), my issues were:
- Some cheat sheet entries don’t have examples, or may lack information on some parameters.
- No documentation on how to write plugins. Also missing documentation on components and the registry, but they’re beta features so I guess that’s coming at some point.
- Little documentation on how to structure your PHP code between plugins, controllers, page models and templates (an overview-with-high-level-example would be nice). As a result I ended up putting a lot of logic in templates, some logic in snippets (!), a few functions in a “plugin”… it’s a bit of a mess, but I didn’t know any better ;).
The documentation search should include the Changelog home and its pages. The documentation’s home page might also link more visibly to the Changelog home.
Cheat sheet pages don’t mention when a feature was introduced. For instance the $media->resize() page doesn’t say that is was introduced in Kirby 2.2, which might trip users of 2.0 or 2.1 who didn’t have time to update an instance.
If it’s not possible to mark all 2.1 and 2.2 features as “introduced in …”, I suggest starting doing so with 2.3 features.
I’m not saying Kirby’s documentation should be overhauled, it’s pretty good, but when a documentation is 95% good then the remaining 5% are pain points that will slow down developers working with Kirby, leading to frustration, lost development time (aka loss of profit) and perhaps desertion. If you get to 99% good, it’s not a 4% increase in quality, it’s a 80% decrease in developer pain.
I also think that “for this release we focused on perfecting the documentation and fixing any stability issues we could get our hands on” can be great for communication. After all, documentation is a feature.
The documentation has regular updates from the team, and I’m not dissing that work. Just thinking a temporary “all hands on deck” focus could have great results. Also the docs are on Github and pull requests are welcome (a few PRs are pending or abandoned by the way). But it’s hard to contribute to, say, the cheat sheet when you’re not the ones building the API, or to documentation articles when you’re not the one setting the tone and priorities for the documentation.
Related topic: All documentation in the docs