+1 On Wed, Nov 1, 2023 at 6:38 AM Jean-Baptiste Onofré <j...@nanthrax.net> wrote:
> Hi Brian > > I like the proposal, it sounds like a good way to "align" our > documentation. > > Thanks ! > Regards > JB > > On Wed, Nov 1, 2023 at 8:20 AM Brian Olsen <bitsondata...@gmail.com> > wrote: > > > > Hey Iceberg Nation, As I've gone through the Iceberg docs, I've noticed > a lot of inconsistencies with terminology, grammar, and style. As a > distributed community, we have a lot of non-native English speakers reading > and writing our documentation. I propose we adopt the Microsoft Style Guide > to improve the communication and consistency of the docs. Common rules like > defaulting to use present tense not only make the documentation consistent > but also more accessible for those who struggle to understand complex > conjugations. Then there are examples like making sure to capitalize proper > nouns like (Spark, Flink, Trino, Apache Software Foundation, etc...). You > may think, that's great Brian, but good luck getting everyone reading the > project and following that. I also want to propose adding a prose linter > called Vale, that will enable us to add the existing rules for the > Microsoft Style Guide, and our own custom rules to ensure consistent style > with documentation changes. > > Let's discuss this in the sync tomorrow! Bits > -- Ryan Blue Tabular
