Looking to help write Phoenix documentation (and thinking about best practices)

[mattei]

Hey friends,

I’m looking to start helping write documentation for Phoenix and wondering where to start. Is there a “help wanted” list anywhere of topics to cover?

I have my personal list of documentation grievances that I’m hoping to help tackle, but I was wondering if there’s a public list out there by the maintainers.

---

P.S. Another question: is there a good resource for best practices for Phoenix? In the Django world, we had the excellent Two Scoops book series, which served as the bible on how to do things The Right Way™.

I often find myself wondering what to do in certain cases (e.g. such as where to place notifiers, where email module files go, how to write good changesets, best practices for context functions). Sometimes I feel Phoenix leaves too many decisions down to me - leaves me wanting a set of guidelines on how to structure things.

A small list of grievances from a Phoenix semi-noob:

• More examples on writing changesets and best practices (separate changesets for each operation?)
• More examples and guides on writing context functions, when to write them and when not to write them
• Where to put things! Where to put Swoosh email functions, notifiers, etc.
• Stronger upgrade guides: the 1.6 upgrade guide didn’t mention Swoosh, I had to copy over things from a boilerplate
• Improving the Swoosh documentation, especially phoenix_swoosh, which is lacking severely. I should make a PR.
• Best practices on writing Ecto stuff and where to put DB calls, that took lots of looking into example codebases like Plausible and Changelog

My biggest pain points are certainly related to Ecto: whereas Rails has great guides on how to use the data layer components for newbies, Phoenix has very few and best practices aren’t clear. These are hugely important to give newbies a mental framework and prevent cognitive overload!

Answers are welcome and I’m really looking forward to contributing to this amazing community! <3

[Sebb]

Can’t help, but I can add a grievance.

I’d like to have more recipe-like stuff. For example I had a hard time adapting heex.

These are the examples you get in the docs:

...
<div class={@class}>
...
<div {@dynamic_attrs}>

But {...} has some really powerful hidden (at least for me) features, see some examples here:

Can't use for-variable in heex - {if for_var == ...} - Protocol.UndefinedError

the shortest I found (by accident) is: <div boolean_attr={@one == 1}>boolean_attr</div> I’d like a list of heex-recepies. Here are some (including stupid ones): <div {@dynamic_attr}>dynamic_attr from assign</div> <div {@dynamic_attr} static_attr="is-static">dynamic_attr with static attribute</div> <div boolean_attr={@one == 1}>boolean_attr</div> <div {%{boolean_attr: @one == 1}}>boolean_attr from dict</div> <div {if @one == 1, do: [boolean_attr: ""], else: []}>boolean_attr kw-list from if</d…

[mattei]

Just saw this post, and as someone who was bit by this exact issue the parent was talking about, I might consider writing an API guide

[dimitarvp]

@Sebb

I’d like to have more recipe-like stuff.

Strongly seconded. This is sorely lacking. I mean, I too don’t want to do everyone’s homework for them but at one point it becomes apparent that the need is there often enough so we might as well contribute such. I still would like to, still can’t due to many other competing concerns. But it’s something I wanted to contribute for a long time.