I am working with Plone since 2006. Also involved in writethedocs.

I like to complain. Sometimes too picky? Working with Plone documentation I can get grumpy, sad, annoyed, angry. I will give a heavily opinionated talk. Please do not feel offended if I talk negatively about the documentation (or lack of it) of your package.

This talk is from a user point of view. You must realize that a good product is not just about the code. You look at the whole package. If the docs are broken, your product is broken.

On the Plone 5 release day, we had links to at least three different versions of Plone in the installer part. Confusing. Lots of old and not working or not checked code examples. Lots of confusing mixups between Archetypes and Dexterity. There were pending (not published) docs about theming. If you are a Plone consultant, you can find your way, or know who to ask, but as a user... No note that lots of add-ons are not working with Plone 5 yet. No note telling that some of the docs are not updated yet. The answer to a lot of questions on irc was: "The docs about X are not finished yet."

We forgot all of that, or had no time: our fault.

The technical stack is great. Plone 5 is ready as consultant-ware. For normal humans, the docs were not ready yet. Strictly spoken, we forgot to care about normal users.

You are done when it works and it is elegantly documented. Do at least something.

Documentation is marketing. It gets you new users much quicker. It can save a lot of time, effort, money.

Think about the process of documentation for your project as the true act of creation. Documentation Driven Development. I did not make this up!

1. You write Documentation.
2. You write Tests.
3. You write Code.

Simple!

You give yourself the chance to think the project through, without getting bogged down in a detail that you will rip out five minutes later.

Developer documentation is not end-user documentation.

It is much easier to write documentation at the beginning when you are still happy and excited about the project, instead of at the end when you are glad you have finally squashed most bugs and can ship it.

It is much easier to have a discussion based on something that you have written down.

Create an easy and friendly landing page. Make it easy to report a bug. Telling people to create an issue on github, is already too hard for some. We should add a link in the overview-controlpanel to docs.plone.org. Make it easy to find articles on docs.plone.org, the search is not great.

Know the audience you are writing for. Are you targeting end-users or developers. Don't assume readers have your skill set.

Always write a readme, even if it is not perfect. At least it is a starting point, and people can help you out.

Don't postpone writing docs, just add a few lines when you are coding.

Include docs testing in your CI setup. If you want to, you can even include automatic screen shots.

Configure your editor. There are plugins for editors, to check pep8, pyflakes, but also docs: ReStructuredText, spell check, maybe link checkers.

Use a git hook to check your documentation when you commit. Look at mr.butler, mr.docs. mr.docs is a Docker image with the same Sphinx setup that we use for docs.plone.org.

There is not one solution to fix it all.

Let's have an open space about improving the situation. Maybe a QA team?

And: docs or it didn't happen!

Questions?

The English of the documentation is sometimes really clear, and sometimes really complex. Simple is better, you may not even need translation then.

The new patterns have tested documentation in their Javascript. I don't think this gets included in docs.plone.org? No, it is not nearly enough. Nathan has written blog posts. The mockup documentation is not maintainable, at least it cannot be included currently, we need ReStructuredText. We are getting there, but the Javascript parts need much more work.

Patternslib has its own documentation. Do we just link to this, or do we want to include it? If it is in core, we want to include it. Patternslib documentation is in MarkDown, but that will work fine. We will have to try it and think what is in the long run most suited.

Barceloneta is a neighbourhood in Barcelona. It is also the default diazo theme in Plone 5.

Every resource has its own purpose, like scaffolding, normalizing. We have variables.plone.less that defines all the variables that we use in the theme. You can change them in the Plone UI, or on the file system.

It is based on bootstrap 3, but is not dependent on it. We took a 'photo' of bootstrap at some point, and went from there. We prepended plone- whenever possible. Oriol Marti and Albert Casado Celma helped a lot creating the Barceloneta theme. The original bootstrap resources are included on Plone.

We preserved Plone legacy classes and ids, to try not to break old themes. Things like: .portlet, .formControls are still there.

We updated breadcrumbs, images, portlets, alerts, control panels, buttons, almost everything.

New viewlet manager: plone.mainnavigation, with the folder sections in it.

We used http://fontello.com to build a customized set of icons. Used in plone bundle and Barceloneta. See Products.CMFPlone/static/fonts. Just load config.json in Fontello and start adding your own icons.

Plone Toolbar. See plone.app.layout and plone.app.contentmenu. Small changes since last year. You can change the orientation in the site control panel, so make it horizontal at the top. Do not forget to make space for the toolbar in your Diazo theme.

For the control panel we also used a Fontello font. Add a CSS class with the normalized name of your new control panel item, something like:

icon-controlpanel-FilterSettings: before {content: \e844}

Easy backend customization, by reusing Barceloneta resources. You can use the backend.xml Diazo rules and related css. In the future you can use the Plone Intranet theme switcher.

We use the new Resource Registries introduced in Plone 5. A resource is a collection of less files and javascript. So it is more like a web component for Plone.

Then you can register a bundle: a collection of resources.

You can do easy customization of ++plone++ resources. Why only allow exactly those resources and not others? I think it can be very useful.

Automatic variables:

@import url("@{mockup-patterns-select2}");

This is available for every resource, used in compilation.

You should no longer fill the javascript_head_slot or style_slot in a template, but in a view do add_resource_on_request, or add_bundle_on_request. Use this if you are going to use it just in one view.

Console script helpers:

bin/plone-compile-resources
bin/plone-generate-gruntfile

Call them with:

--site-id=myplonesite --bundle=mybundle

A pure Diazo theme is easy for a designer to jump in. Distributed through a zip file for import and export. Diazo bundles preserves this pureness. This uses new attributes for the manifest.cfg file of the theme, like enabled-bundles, tinymce-content-css, production-js.

Some best practices:

• Probably no best practices that fit every scenario.

• Reuse Barceloneta as far as you want. There is an optional Barceloneta profile to register its resources. If you want this, then in your metadata.xml add this as dependency:

  profile-plonetheme.barceloneta:registerless
  

• You are not tied to bootstrap, you can use what you want. Bootstrap is probably easier though.

• Don't be obsessed with the number of requests your site is doing: HTTP 2.0 is almost here, which helps a lot. It is still important, but it will be less so.

• Skin layers are not allowed. Okay, they are still there, but please don't use them. Use plone.resource instead.

• For overriding resources: use z3c.jbot.

• You can use the extend feature:

  .context:extend( .btn-primary) { }
  

• Adapt the grid in Diazo if you want, or via a custom transform like Mosaic is doing.

• Do not create a theme from scratch yourself, but use bobtemplates.plone. Understand the structure of the default theme.

• TinyMCE: custom generated style sheets. Define the new Diazo Tiny content specific css in manifest.cfg. TinyMCE content templates are now in core.

• You can define an nginx passthrough for static plone.resources, so ones that are ++something++. Point it to the local file system for that package, probably using collective.recipe.omelette.

Useful tools:

• Chrome reloader: Eric Brehault's button.
• ?diazo.off=1 and ?diazo.debug=1 in the url
• @@test_rendering page with the common rendering items of Plone.

TTW (Through The Web) is back. You can change the logo in the UI now. plone.app.theming has more power than ever before. It can attract new people. It is easy to do things that should be easy, so non technical people can try out Plone fast. And complex things are possible.

You can try out collective.jbot as customization story, not to be confused with z3c.jbot. Should work on Plone 5 soon, please help.

Overriding ++namespace++ would be nice, especially for sites where you have different parts that want to look slightly differently.

If five add-ons add five bundles, this may be much. We may need to find a better way for this. Also, if all those bundles depend op jQuery, you will get five big bundles, plus the default big plone one.

I came to know Plone during my Google Summer of Code this year. I never used Plone before, but I started loving it.

My project was about transforming safe html, to do that with lxml now.

Plone is one of the most frequent participants in the Google Summer of Code, which I found a plus. The people on IRC were really helpful during the initial phase. You really helped me a lot! And there was awesome documentation. If you start from the first page, and on and on, then it will be a nightmare, but if you know what you are looking for, it is awesome.

I came across this ticket: https://dev.plone.org/ticket/14929. Proposed by Tom Gross, who had earlier tried it, but ran into many test failures. plone.transform was an earlier try as well, during GSOC'07. We had discussions, about moving it from how CMFDefault did it, to using lxml. Thought about the intelligenttext transform too.

I had difficulties working with Plone. It is not easy for anyone who is new. The code base is vast. The first two months it felt very alien. Difficult for me to figure out where to start. The safe_html of portal_transforms is quite old, and I was not used to those libraries, but I did need to know what this code was actually doing.

So lots of difficulties, but also lots of fun. I learnt how to work in a team, often asking 'can you help me?' I learnt new things about Plone, and how fun it is. Learnt how to write efficient code, and how to document how I did it. Pep8, indentation, etcetera, producing good code. Test driven development, I never tried that before. This is one of the best parts of Plone. I got to interact with cool people. They taught me a lot, including some new beers of Europe.

Main goal: get rid of the transform we were using from CMFDefault.

The new filter. Lots of things required to setup the add-on, generic setup, browser view, control panel, interface, an uninstall profile. We have automatic registration and unregistration, done when installing the add-on. Package is: experimental.safe_html_transform

Code: https://github.com/collective/experimental.safe_html_transform

New releases of Plone were done, and suddenly tests started failing. plone.app.widgets was not pinned and got pulled in, and the latest version was trying to pull in the latest CMFPlone version, which was too high at that point, giving an version conflict during buildout.

We created a new control panel, with separate permission.

The new transform uses lxml. It converts the document into the tree form and parses each node of the tree. It checks if the tags or attributes are safe, strips or removes them if not. lxml is faster than the previous solution from CMFDefault.

We used unit tests to test the transform, with sample html. Also automatic robot tests for the control panel.

Now TinyMCE should use our new transform. It uses getToolByName to get the portal_transforms to get the registered transform by its name: it wants safe_html. So we renamed the transform to safe_html.

One thing left: integration of control panel and script.

I learned test driven development, collaboration with people on a project, also a big project, how to understand errors from the error logs, how to keep logs for huge projects (blogging, task managers, etc), because you will forget what you have done five months ago.

Plans: I started loving Plone, so I look forward to learning more about it. First I will finish this project.

Most of the people in India do not use Plone. In my university no one used it. That is a barrier for picking up such a project from GSOC. More awareness is needed, so people are not stuck with Wordpress and need to learn the basics of Plone still.

I never took a training of Plone, that would have helped, like I did this week.

I will be here for one day of the sprints. I would like to work with you.

I have been involved with ICT accessibility since the mid nineties. I was a developer of the FreeBSD project. I am a Unix server admin, web admin, accessibility advocate, podcaster. And I have used Plone for about five years.

I am totally blind, almost since birth. But I can use a PC and such.

There is no universally accepted definition of accessibility, as far as I know. It depends on the context. For me: information or service can be accessed by 'everyone' with virtually equal costs.

Who is everyone?

• With or without disability.
• Age.
• Situational: if you are driving a car, you cannot pay much attention to visual clues; in a quiet library you should probably not use audio; maybe you temporarily cannot use your hands.
• With different devices, not just PCs.
• Language, not everyone speaks English or Japanese.

So how about the costs of access?

• Can be simply a financial cost.
• Time: without hands, you may need more time for some actions.

You first need to know content is there: I cannot see an image without an alternative text.

Key to accessibility is:

• Make everything machine-readable.
• Help assistive technologies.

What are assistive technologies?

• Software or hardware to assist users with specific needs. For example screen readers. Several operating systems have packages for this installed by default.
• Magnifying part of the screen.
• Alternative input devices. Keyboards with very large keys. Complicated switch interfaces.

Machine readable:

• If you show an image of a character, versus text data, most people will be able to see them both. Machines cannot, unless they have image recognition.
• You can make text visually larger and bolder, or you can explicitly enclose it in an h1 tag.

What needs to be machine readable?

• Content to be presented. Have alternatives for images.
• Roles and states of UI elements. Identify menu items as menu items.
• And everything else if you can.

Besides this:

• Is there enough color contrast?
• Are the characters large enough? I can still 'see' 1-point fonts, but most people cannot.
• Can text be resized by the visitor?
• Make it easier to operate. Timeouts, like you need to finish a form within ten minutes otherwise you are logged out, can be hard for people with a disability on their hands.
• Do not autoplay audio, because then I cannot hear my screen reader anymore, so I cannot even stop it and will just leave the page.

So what specifically can you do? See Rob Porter's presentation: http://maurits.vanrees.org/weblog/archive/2015/10/rob-porter-how-you-can-become-an-accessibility-superhero

From a technical aspect, you are opening up to a broader audience and an increasing variation of access devices.

There may be social or legal aspects. There is an aging population that needs reading glasses. Don't worry about me there. The US has legislation, other countries too.

Why Plone? Possible choices for me were Movable Type, Drupal, Plone. What did I want?

• I should be able to manage it, edit it, and use it.
• Multilingual support.
• I want an inexpensive license.

Movable Type was not a practical choice.

Drupal: I did not want to use PHP. Actually it is doing really well for accessibility.

From a blind programmer's perspective: Python sucks. You have to count the spaces. But still better than PHP's incompatible upgrades and stuff.

Accessibility in Plone:

• Really good up to around Plone 3 days.
• In Plone 4 it was outdated.
• Plone 5: not perfect, but a bright future.

The accessibility info page was well written at first, but was forgotten after a while.

Up to Plone 4.x: Kupu was inaccessible, at least for me. No critical issues with generated content. With third-party products it was a different story.

Plone 5:

• Many outdated techniques have been removed.
• Accessibility page rewritten.
• Recent TinyMCE is completely accessible. Really good. I don't have to disable it anymore.
• I see increasing interest and attention from developers.

Room for improvement:

• Javascript widgets need to integrate WAI-ARIA: use roles and states for assistive technology.
• Some issues with color contrast of default theme.
• Diazo editor is not accessible.
• Need to raise awareness in community.
• Well written documentation for theme editing is needed.

Then Plone 5 could be a good choice.

If you are using assistive technology, give more feedback to the developers please.

Look at the web content accessibility guidelines: http://www.w3.org/TR/WCAG20/

Slides: http://www.accessibility.org/~max/talks/201510-plone.html

Twitter: @mnakane (English), @ma10 (Japanese)

This is part two of a talk I did in the Brazil conference two years ago. Recap:

• Every non-trivial upgrade should be approached as a relaunch. Look at content, site structure, design, underlying packages, different languages to use in the site.
• The primary challenge is not development, but communication and project management. It is not just a new version number.
• Bring time. And space. You need to do all steps multiple times. Get lots of disk space. Keep several copies of the database so you do not have to start over at point 1 again.
• Expect everything to break. Templates, python files, add-ons, etc.
• Don't experiment, document. Write every problem and solution down. It is not done, you have just done it on a test migration on your laptop, you will have to do it later on the live site again.
• Write your code as if your own kids will inherit the code one day. You don't want them to hate you. You need to understand what it does one year from now.
• Write upgrade-steps in your add-ons, so you can just run it and not have to do all kinds of stuff manually.
• Divide and conquer. Once one step works, commit the changes and make a copy so you can worry about the next step without worrying about the old steps.
• Don't try more than two new technologies at once.
• Use the help. Use plone.api. Use ftw.upgrades, several nice helper steps.

Now upgrades from Plone 4 to 5.

Why would you want to migrate? Why would the client want it? Do you simply want to play with shiny new tools? If the site is running just fine, they can stay on Plone 4. Are there any new things in Plone 5 that they really need or want?

• Great responsive design out of the box. But they may already have it in Plone 4.
• Newer TinyMCE? The editor just always has some problems, no matter which Plone version.
• Security? Hard to sell.
• Prototyping can be easier, say for dexterity, but how often to you prototype on a live site?
• New folder contents, new UI: yes, many will like this.

So do not force your client.

Demo of upgrade of small site. Includes optional upgrade from Archetypes to Dexterity content types.

You lose one thing: the content history, so the CMFEditions revisions. That is really hard to do.

Demo worked fine. It can't be that easy, right? When the old site has lots of configuration and installed add-ons, it gets trickier. Many add-ons still need changes.

• LinguaPlone is hard to get rid of. You need to migrate this to plone.app.multilingual 1.x in Plone 4 already.
• Theming is tricky. I got an error when trying rendering anything. I saw I had to install plone.app.theming manually.

Use PDBDebugMode to debug tracebacks.

Please work on problems like this, document problems, fix problems, report them.

Read the upgrade guide and work on it during this sprint: http://docs.plone.org/manage/upgrading/version_specific_migration/p4x_to_p5x_upgrade.html We will upload this to a Google doc so more people can work on it this weekend and get it properly integrated later.

Disable your custom theme before migrating, otherwise it will break. Use the new Barceloneta diazo theme as basis and work from there.

Archetypes content types will still work just fine, maybe some less nice widgets in editing. You should migrate to dexterity.

Move everything to the portal registry. All settings are there. So no longer set something in for example the portal_properties.

Before you work on your custome code:

• Figure out if you still need it, maybe the problem it tried to solve is already gone.
• Use plone.api for anything you write new or that you change.
• Formlib is kind-of gone. Custom forms should be done with z3c.form.
• Portlets are also moved to z3c.form.
• Check any templates that you override, take over changes, or remove the override.
• For custom migrations from Archetypes to Dexterity, look at these views: pac_installer, atct_migrator, migrate_from_atct, custom_migration.