Proposal for Consistent Capitalization in Documentation Titles

tldr: I propose we standardize on Title Case for the Phoenix and LiveView documentation.

A code review suggestion by @josevalim made me realize that section titles in Phoenix and Phoenix LiveView documentation don’t follow a specific pattern.

From what I’ve been following of Elixir and Phoenix, there’s a push to improve the quality and polish of documentation, among other initiatives.

I believe consistency, in particular consistent capitalization, makes for more pleasant documents that are easier to read on screen and in print, adding an extra level of polish to match the quality of the content.

A screenshot to illustrate the current situation:

Many titles capitalize only the first letter (e.g. “Security considerations”) and proper nouns (e.g. “Assigns and HEEx templates”). However, some others use Title Case (e.g. “API Reference”, “External Uploads”, “Debugging Client Events”).

At the main Phoenix docs, most top level titles use Title Case. There are exceptions, so it is not fully consistent. Another illustration:

Considering the common practice in published English works and the recommendation of many style guides, I propose we standardize on Title Case for the Phoenix and LiveView documentation to make it feel consistent and familiar to the community.

If the proposal is accepted, I volunteer to document the style preference in the repos and update existing titles. Since only capitalization would change, there would be no impact on existing links as they are all downcased anyway (e.g. “Debugging Client Events” is at https://hexdocs.pm/phoenix_live_view/js-interop.html#debugging-client-events). The updates can be done in multiple stages without prejudice to the end result, thus avoiding huge and hard to review PRs.

PS: As an extra reference that uses Title Case, consider the Erlang Reference Manual User’s Guide.

I would love to hear feedback from the community