search

plone / plonecli

Plone Command Line Client - for creating and working with custom add-ons and themes
https://pypi.org/project/plonecli/
Other
19 stars 10 forks source link

Improve reST and accessibility of README and docs #12

Closed svx closed 6 years ago

svx commented 6 years ago

This PR fixes various accessibility issues by improving reST. By doing so the docs (and README) are now better readable for screen-reader and easier to translate.

Further on multiple fixes for wording and qa (like GitHub in place of Github)

Improving the README by adding info about docs, etc

Consistent headings

For now that is all, there are more issues like the usage of include and creating double content and such. But yeah this not included in this PR :)

jaroel commented 6 years ago

@svx Is capitalising every word in a header really better?

svx commented 6 years ago

@jaroel Headings are a kind of grey zone. There is no better or not better. Everyone is doing it different, FB is doing it different that Stripe and there are doing it different than Mozilla, Google, $NAME_A_SHOP.

It boils all down to consistency.

For the docs on plone.org we decided a long long time ago that we use the every first letter is in capital style

See also: https://docs.plone.org/about/contributing/documentation_styleguide.html :)

If you diff or look at the changes I made in this PR, you will also see that I did not changed all headings, I 'just' made sure that they are consistent, since lots of them were already following 'our style' :)

In generally this is some kind of 'hot topic' in the technical writing world since years, but so far there is not really some kind of best practices. :)

jaroel commented 6 years ago

@svx You live and learn :D

svx commented 6 years ago

@jaroel one reason for example why we decided for it is that it makes docs easier to read, because it clearly shows visible the difference between a header and text.

For accessibility this helps, too