Define writing style

[pitrou]

It seems there are some inconsistencies in the cookbook's writing style.
For example:

• verb tense in titles: "Write a Parquet file" vs. "Reading a Parquet file"
• capitalization: "IPC" vs. "ipc", "parquet" vs. "Parquet", "numpy", "Arrow array" vs. "Arrow Array", etc.

[thisisnic]

Should this be consistent across the different implementations of the cookbook, or only matters to be consistent within each implementation?

In the case of the capitalization point, I think it'd be really helpful to have a style guide which is applicable across all versions, though I'm not sure with the verb tense point whether this should be up to each individual implementation to decide.

[pitrou]

Ideally, very general concerns like this should probably get a consistent answer, IMHO.

Besides writing style, there's the topic of trying to define the typical structure of a cookbook entry (for example: problem + solution + optional elaboration), so that searching through it yield a consistent experience.

[pitrou]

cc @amol-

[thisisnic]

That makes sense; I absolutely agree that consistency is important for writing good docs (and something we can do with more of).

I just want to be careful not to prioritise consistency above the needs of the different audiences for the different cookbooks; the typical Arrow C++ user is likely a very different person with different skills and aims than a typical Arrow R user, who in turn is different from a typical Arrow Python user etc etc, and I want to make sure each implementation is able to cater best to the needs of their audiences.

[amol-]

I think that for the titles it makes sense to stick to a verb standard. Mostly to make sure the index of the cookbook doesn't look too odd.
I'm personally less concerned about capitalization as there will be cases where you want to use Arrow Array because you mean specifically the Array class or Arrow array when you are talking more in general of arrays as a data structure.