New: Learn Statamic on Laracasts!

We've retired the forum in favor of GitHub Discussions.

New conversations can be started on GitHub. Existing conversations will remain for a while longer.

Head over to GitHub →

I have a (trivial) problem with your documentation

bvm June 15, 2020 by bvm

Hello, I am just now getting started with Statamic; I will be migrating the website of the company I work for to it over the next couple of months. Right now I am getting familiar with the nuts and bolts and I have a small complaint about the way that some of your documentation is written:

While I do find this highlighted portion funny it is also pretty long, and what I've found in the few hours I've spent with your documentation is that these jokes are becoming quite obnoxious.

I fully empathize with the relief writing in such a way brings to the tedium that is developing technical documentation, and as a strategy to help push yourself to write more than you normally would on a given day--all while bringing some levity to a subject matter that is otherwise dry as sand--it is genius.

However I'd like to suggest something that you may have not considered: the length of this humorous text and their frequency in the documentation works against developers on tight time budgets, and those, like me, with humble cognitive load capacities.

It is not easy for me to wrap my head around a new concept while simultaneously parsing facetiousness.

Over the coming years I will be returning to this documentation hundreds of times, that much is sure. I am already dreading it and hope you will consider whether the next joke you're about to write really deserves to be in the documentation for your extremely good product. If the answer is "yes", it can stay, but if this post made you double-check I consider that a win for everyone who is having trouble with these asides (there may literally be dozens of us).

Answered by Jack McDade!
>>>>>>> Answered <<<<<<<
1 Reply
1 Follower