Documentation Suggestions

[CaelanStewart]

Summary

Hi,

I'm approaching Twill as a new user, with moderate Laravel experience.

I really like Twill so far, and I can see its potential to save time with the right toolkits and component libraries – however, there were a few things I felt were under-explained in the documentation. Things which I feel detract from the speed of onboarding without people around that already know it well to answer questions.

The issues I found were, fairly generally:

1. There are lots of tidbits that are quite important that relate to various concepts that are distributed around, and not clearly or explicitly stated up front in important information boxes or bullet points, such as whether migrations are needed for blocks and fields
2. Ambiguous language open to multiple interpretations, where I'm left wondering which interpretation is correct, having to try and narrow it down
3. It isn't clearly explained how to create a singular pages which are used, for example, as a front-page. It is sort of by example in the buckets section, but really a section on singular pages (or even a home page example under a specific homepage section in the docs)
4. It isn't clear how repeaters are rendered – everything about actually rendering the content of blocks and repeaters is left very, very open to interpretation. I know the point is that Twill is fairly unopinionated on how content should be rendered on the frontend, but this makes it difficult to figure out from your docs alone the best ways of approaching this given the semantics of your framework
5. No use of alert boxes containing important information, such as how Laravel handles these things
6. It doesn't clearly and comprehensively describe the purpose, allowed types and values of arguments/options to many Twill blade functions and class methods

Examples

Example 1
Under "Form fields > Files" you have this code snippet:

public $filesParams = ['file_role', ...]; // a list of file roles

The term 'role' is already used for User roles, and presents an alternative and misleading interpretation of the above comment, which had to be clarified.

Example 2
It isn't described very clearly where the icons come from, except as an unexplained option in the default twill.php configuration section. These things were fairly easy to find out, but I feel there have been a lot of these things, and together culminate in a consistent theme of lacklustre documentation.

Describe the solution you'd like

1. Use more explicit language, and carefully consider possible misinterpretations, and proactively mitigate for them by making the language and terminology completely clear, unambiguous and comprehensive.

2. Use alert sections like seen on Laravel:

3. Have more complete and thorough examples, like a complete demo project that uses every feature of Twill in some simple and common use case.

4. Have more detailed tables and descriptions of options and their allowed values and types. WordPress, which I'm very happy to move away from, was admittedly very good at documentation, same with PHP. They are more mature projects of course, but I'd love to see Twill become the replacement for WordPress!

[CaelanStewart]

Have updated the issue now (after accidentally posting it half-baked!)

[CaelanStewart]

I have found some more issues with the documentation.

And also on the part of Twill, the primary thing I think is the biggest issue is leaky abstractions, there have been so many little gotchas to consider as you drill down into the details, it's getting a bit frustrating. This was not my experience with Laravel or even any other framework or library I have used, at least not to this degree.

• $mediaParams is hardly explained at all. I want to have an image be resized, but I don't want it to be cropped. It isn't clear how to do this, and there is no mention of this I can find in the docs.
• By default, using the local media driver, transparent PNGs are converted to JPGs with a white background (and it isn't clear how to make it just use the same format as the original without digging into Glide and the specifics of how Twill merges default options (setting fm to null in default_params in config/glide.php doesn't work). If Twill internally uses the null coalescing operator and passes a string as its right operand then my null will have no effect, so I have to read all of your code to find this out).
• There is no documentation on getting modules by slug (except halfway through one of your tutorial videos (which I had to play at 2x speed because he talks too slowly)), or general best practice approaches of generating URLs to module instances and the best places to put this code.

I'll keep posting the things I find here, as despite the docs I do for the most part really like Twill.

[pboivin]

Hi @CaelanStewart,

Thanks for your feedback! I'm taking the liberty to convert this to a discussion because of the breadth of topics covered. Feel free to open more focused and actionable items as individual issues.

I hear you... the docs are not ideal. A few things I can say about that:

We are actively working on the documentation

I'm a relatively new contributor to the project so, my understanding of Twill's history is probably incomplete. Even so, it's quite clear to me that over the years, the rate of new features and fixes outpaced the work on the documentation. I agree that it's behind what it should be.

For what it's worth, we are constantly making adjustments to the 2.x docs, while working on a complete (or almost complete) rewrite of the docs for 3.x. You can expect more on this in the near future.

In the meantime, your help will be appreciated! From my point of view, the barrier to entry for contributing to the documentation is very low! You can make edits and send pull requests directly from GitHub.

Twill does require experience with Laravel

You hit a very important point there, which I think can be improved. It's true that the docs in their current form require a certain level of experience with Laravel. I believe Twill docs can and will be update to make it easier to learn Laravel with Twill.

All things considered, your feedback is very constructive and I thank you again for it. I can only encourage you to contribute and shape the docs in the direction that you want.

[CaelanStewart]

@pboivin – Thank you for the response! I did wonder if perhaps the docs were being left for a rewrite and a new major version.

Indeed Laravel experience is needed, though I don't feel that was the primary reason for my gripes. I've dug fairly deep into Laravel for some pretty comprehensive custom apps I've built where I'm working, just none with Twill, including some custom extensions to implement recursive relationships through recursive CTE where the staudenmeir/laravel-cte package couldn't handle this edge case. It's just that I don't have many years of Laravel under my belt, hence the term "moderate".

I'm happy to read code, but I feel that's a last resort, and docs should be the first pass.

To be honest I found Laravel Spark to be the worst documented thing I've ever used! Though the main Laravel docs I've found generally cover all of the really important bits.

[CaelanStewart]

Oh, and I meant to say, I'd love to help contribute to the docs soon.

Is there a roadmap for 3.x? If it's due for release pretty soon then there's probably little point significantly working on the docs for 2.x, especially where Twill isn't in wide use at the moment.

[pboivin]

That's great to hear!

The roadmap is shaping up there but it's not quite set in stone yet :
https://github.com/area17/twill/projects

Same goes for the docs rewrite and the 3.x release date, nothing confirmed at the moment. In any case, feel free to contribute to the 2.x docs. This has the potential to be useful in the short term and all contributions to the 2.x docs will be included in the rewrite.

[CaelanStewart]

One particular trait which I think makes it harder for me to interpret these docs is that I do not like to make any assumptions. I like to go into what I'm doing fully cogniscient of the process, so I will often spend quite a long time thinking and reading the docs before I even write any code.

I don't like to just "try stuff" and see what happens.

Hence why I feel ambiguity is important to minimise, and so too make clear the really important points about the structure of the features in question.

[pboivin]

I have to say I personally disagree with this observation :)

"Just trying stuff" is the best way to make progress in my own experience.

[CaelanStewart]

@pboivin – Most definitely! I don't meant to imply it is a bad thing at all!

Generally when I do just "try stuff" I find out what I needed. Though there's also the danger of trying stuff and it working, but only by accident, and really It was founded on a misconception, which could then be tricky to pick up later on.

Hence the term "trait" – definitely something I could work on improving. :)

Thank you again