Docs: Please follow our style-guide and best practices

Hi,

First of all it is awesome and really great that people start writing docs about how to migrate to Python 3 !

Thanks you!!

But, please can you make sure that you follow our style-guide and best practices about rst practices from the beginning ?

Going later on though all these files and fix them, will be a huge effort and we are trying really hard (since the PloneConf in Brazil) to fix and improve the quality of our docs in general.

Again, it is really nice that you take time to write docs, but please also make sure to follow our best practices and style-guides.

For example: https://raw.githubusercontent.com/plone/documentation/5.2py3/manage/upgrading/version_specific_migration/upgrade_to_python3.rst

really needs some attention, that document is currently mixing various styles and has lots of room for rst improvements.

We want to archive docs which are understandable and readable !

So, please, please follow our guides they are there for a reason, the same as you/we have tests for code.

Thanks !

This is by all means not meant to be offending or something.

To help developers toward the path of good documentation, what are the canonical links to the Style Guide and best practices? Let's be explicit, please.

I updated https://github.com/plone/documentation/issues/1024.

I am sorry that I forgot to mention them, by now, I thought people know that we have those, since we are telling and adjusting the docs according to them since years.

One more thing, as I ( and docs team) already told/wrote, here is a reminder !.

We will be more strict from now on about PPs and merges, for the last years we were always kind of polite and accepted lots of contributions with really really bad style/wording/syntax.

This will change from now on :slight_smile:

What does that mean ?

That means that from now on we will be a tiny bit more strict. We really have to improve the all over quality and readability of our documentation.

  • No merges with typos
  • No merges of docs in PEP8
  • No merges of documents which are longer than 800 lines
  • No merges from contributions who not follow a least some parts of our style-guides about:
    --> code-blocks
    --> style for headers

Links:

This may sounds harsh, but this is really minimal stuff, we have to start at some point to improve.

We will also update the PR templates on GitHub to stress this issues more and hopefully make them more clear.

I am sorry people, but as far as I see it, lots of you can do that with your code contributions but for some reasons you always forget to follow at least some basics for docs.

Like I said already many many talks:

Code = Docs

And btw, you can always ask us (docs team) :slight_smile:

Love you all !

3 Likes