What I’d love for Kirby 2.4: refine the documentation :)

Kirby 2 Suggestions 💡
#1

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.

Navigation

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 $page section 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. :slight_smile:
  • 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 ($page->children and $pages->children), and maybe hand-picked “see also” methods.

Content

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 ;).

Changes

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.

Wrapping up

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. :wink:

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.

Post-scriptum

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

6 Likes
#2

Thanks a lot for your feedback, @fvsch. In fact, I agree with most of what you say, and a lot of the points you mention are already on our to-do list.

There will be a better search function in the near future. We have also planned to separate the blog “How Tos” into a tutorial section. And you are very right as regards the position of the cheat sheet, it should really be in the main navigation.

As regards the new features of the beta version, we hope to have most of that ready when the final release comes out.

1 Like
#3

Another example of (slightly) shallow doc + (mostly) problematic search and navigation: the routing doc.

  • Searching “routes” or “route” does not return the “Routing” guide. You have to search for “Routing”. (Perhaps the main guides would benefit from having some keyword aliases that can be used while searching and in the autocomplete.)
  • Searching “rout” does not return the “Routing” guide either. Maybe it’s returned after 10 other results from the Cheat Sheet, so it gets cut off. Perhaps the “guide” pages should be weighed higher to appear on top?
  • Searching “route” does return some Cheat Sheet pages, but they’re not really helpful:

For the record I managed to find the “Routing” page not through the search, but by checking the “Advanced” section (thinking “this is nonsense, they must have documented the routing mechanism somewhere right?”). Also I knew to check the “Advanced” section because I already know the docs fairly well. :wink:

1 Like
#4

As @texnixe wrote, the search will be improved quite soon. Actually we are working on it right now and it will be dramatically better. Thank you very much for your feedback however. :slight_smile:

1 Like
#5

I always use Google in order to find stuff on the Kirby Docs page :stuck_out_tongue:

Something like site:getkirby.com/docs/ "get page slug"

That way I get more (satisfied) results than using the native Kirby search-engine.

Another point; please make the searchbar available from every page in the docs;

Now it’s only available from https://getkirby.com/docs/ …but when you click on a link, you can search any further.

Please notice; this is no critique - but just my penny :stuck_out_tongue:

#6

I can only repeat: We are working on this and the new search will have these features. :wink:

1 Like
#7

are you mean the search in the Panel or in the Docs?

#8

In the docs on the Kirby website. :slight_smile:

#9

@lukasbestle oh okay :wink:

#10

Good news for the search part. :slight_smile:

#11

A subdomain for the cheatsheet would be nice.
“cheatsheet.getkirby.com”

:gift:

#12

While we’re dreaming…: I’d love to see Kirby docs included in Dash, and of course, DevDocs…

#13

Do you know the inofficial Kirby Dash docset?

2 Likes
#14

Thank you for the pointer, @lukasbestle!

#15

It would be nice to make the blog searchable too. I found some nice gems there - most of them are still working. But sometimes I forgot where I found stuff and was searching in vain.

#16

Can we have some details on how you implemented the search?
I would be highly interested since i am also looking for a good solution for a project :slight_smile:

Thank you and great news!

#17

I have sent you a direct message.

#18

Great idea. Also, some example are out to date, or there is a better way to do it, or go find another way to to immediatly in the next entry. When I started Kirby I was totally lost in pages methods with page(), $page(), pages ()… hard for a newbie.

Same for certain functions, I don’t know which are deprecated or not (or just least used) so my code is full of different code to achieve the same result (like find a page).

When you start with Kirby you look in the cheat sheet and in example blog posts like the “one pager” but method described in each doc are different for achieving the same thing.

The lack of examples in cheat sheet is also hard for non-developpers.

As @fvsch said, it’s a good documentation but the 5% of inconsistencies can totally lost you as a newbie.

#19

We can only repeat, we are constantly working on the docs, improving, adding and updating stuff; there will be a Getting Started Guide soon, I think, and have recently merged a compendium on filter methods which is already online.

You can help improving the docs by letting us know what is missing or outdated, though. The best place to do that is by creating an issue on GitHub in the getkirby.com repo.

1 Like
#20

e.g.:
the hardcopies and there text “Creating your first account” at https://getkirby.com/docs/installation/panel are outdated at least with about Kirby 2.2.0. We don’t see the second hardcopy during the installation of the panel any more and the first hardcopy has changed with Kirby 2.2.3 I think.