Checklist

A Checklist For All Trainings

Repository Structure For the /

• A main conf.py (for training.plone.org)
• Main test directory
• Main build (make) file (for build and deploy all)
• Main index
• Main /about with good content and info about all trainer
• Main glossary
• A /docs with documentation about writing style, testing, deployment, etc,..
• A _static directory for media/images
• Link from index page to about to explain and more info

Repository Structure Per Training Directory

Each training lives in its own directory and should be able to build by its own.

• A conf.py, configured per training
• A index.rst
• Include main glossary, add there special terms for your training ¹
• Include main about which holds all info about trainings, trainer, style-guide, etc, etc

Tests

This tests will be run against the repository via CI.

However if you start writing it would be helpful and faster to include these already in your local writing flow.

• reST linting (for sphinx)
• Spell-check
• Word consistency (like GitHub, JavaScript)
• No 'So' at the beginning of sentences
• One sentence per line
• Line limit more or less 130 characters
• Documents not longer than 600 lines
• Link-check
• Catch insensitive, inconsiderate writing (http://alexjs.com/)
• (Certain) weasel words (https://github.com/btford/write-good)

Bonus Tests

• Check for Unexpanded Acronym

Testing Tools

• https://github.com/testthedocs/ttd-textlint
• https://github.com/testthedocs/plone-docsbuilder
• https://github.com/testthedocs/plone-lint
• https://github.com/testthedocs/henry

Deployment

• Build and deploy every training 'standalone'
• Build and deploy all in one

Notes

1 Example: In the deployment training we have AWS (Amazon Web Services) as 'special'. ↩