search

ansys / pydpf-composites

A Python wrapper for Ansys DPF for the post-processing of composite structures.
https://composites.dpf.docs.pyansys.com
MIT License
8 stars 1 forks source link

Review project documentation #160

Closed jorgepiloto closed 1 year ago

jorgepiloto commented 1 year ago

One of the steps for the technical review is to be compliant with the documentation guidelines.

The documentation style check was implemented in #125 and some errors got fixed. However, warnings are still present, see this CI/CD run.

Hence, I would love for the @pyansys/documentation team to review the documentation for this repository. I offer myself to contribute as much as required to speed up things.

greschd commented 1 year ago

Regarding some of the remaining Vale warnings:

The top-level headings in the API reference contain feature names, such as Sampling Point. Guidance we got for our main product documentation (ACP) is to capitalize these with each first letter in uppercase.

To be locally consistent, we decided to capitalize all the titles in "API reference" the same way, but would be happy to change if that's deemed better by the docs team.

jorgepiloto commented 1 year ago

Pinging here @PipKat. I would love to have her guidance on this.

PipKat commented 1 year ago

Ansys has a crazy "habit" of randomly capitalizing words in their documentation. A "Composite Model" isn't something unique to Ansys but rather a descriptor of a common industry term! Random capitalization in our documentation greatly reduces its readability! This "habit" also goes directly against guidelines in both the Microsoft Manual of Style (which is used for writing our product documentation) and the Google developer documentation style guide (which we are using for our developer documentation). Both guides indicate that you'd use capital letters in such situations if you have to do so to match the capitalization of UI elements. Our developer documentation is adopting the more modern conventions of these continually updated guides and not following old Ansys habits/conventions!

P.S. I will admit that having titles in sentence case took even me a long time to get used to--but both of these style guides now recommend this approach!

greschd commented 1 year ago

Ok, I guess that means we should use sentence style everywhere.. since as this being a library, it doesn't have UI elements by itself!