If you still think documentation is about "how stuff works", you are doing it wrong. There is a lot of software around, people have lots of choices, people being future clients, developers, users, community members.

Also, your future self will thank you. It is good to know what that idiot was thinking half a year ago.

Sometimes you just want to use a four letter word: RTFM. Read the fine manual. But then there has to be a manual. If people don't know Plone, they won't use it.

A year ago, in Brasilia, a plan was born. We were really unhappy with the state of documentation last year. Spread around over the internet.

A robot master, documenter, marketeer and 9 others walk into a bar and... Well, it was an office, well there was a bar involved, but anyway. Sisi Nutt did a lot there. Without her the documentation would not be so far as it is now. It has been tested on live humans (testing on animals is not allowed).

We had a reality check on the Write The Docs conference in Berlin. Good to get input and feedback from other people. We are now testing broken links using continuous integration, which was new to them.

So now we want more, better, nicer, shinier, sweeter. What we are now telling about documenting Plone, you should apply that to your add-ons too. If it is not documented, it is not used.

• Define what the audience is of your documentation, or for a specific part of your documentation. Structure your docs accordingly.
• Soft landings are important. So add introductions. Let people see if this chapter is what they are looking for.
• Get the tone right. Friendly and professional go a long way. Don't scare off users, unless you really want to. Ask for help, especially if English is not your first language.
• Consistency. Don't leave your readers hanging, nor your contributors. Always use the same terminology. Write and follow style guides. Do not make it too complicated. Read the Zen of Python (import this) and apply it to your documentation as well.
• Versioning. Different software versions need different docs. Benefit: you can retire the old. This is what we will do soon. On http://docs.plone.org you will see the Plone 4 docs by default, and can choose a different version.
• Spellcheck is a wonderful invention, please use it.
• We love humor. Please do not do that in documentation. Highly culturally charged. It gets old quickly and docs are meant to last.
• Sarcasm is never a good idea in docs. Nor in irc, for that matter.
• Testing is essential. Test it on somebody who is not an expert in the field. Does your audience get it?

Now for some tools. Search docs right from Sublime. It has integrated search for Chrome, Firefox, DuckDuckGo. Or using Dash (OS X) and Zeal (Windows, Linux).

Quality control. We have robot screenshots. Automated spell check. We add some words to the known words list, which doubles as a Kudo list, for example we have added David Glick to that list, otherwise we get errors from the spell check.

Development time is a very limited resource. I think that time should be dedicated to coding, and not do things that can be outsourced.

Why should you listen to me? I like to be on the water, surfing, diving, and I do that a lot of days, much more than previously. So I have less time to do actual coding. I really need to get stuff done quickly, no distractions.

You don't want to tinker with your mail server if you can outsource that to someone else who is probably better at it than you.

Continuous delivery: deliver value for the customer all the time. When something is pushed to master, it is automatically rolled out on production. It makes the developers really attentive to details: it really has to work, not just roughly.

There is a problem: a bug, feature request, anything. You code it, push it to a branch, do a pull request. Another developer looks at it. Travis (continuous integration server) runs the tests. If all is fine, it is pushed to Heroku. This usually happens several times a day.

When you have code running in production, errors will happen. So we use Sentry for errors and Papertrail for logs.

Why is not everybody using Travis? Free for public code on github. Run a test script when changes get pushed. Private repos are supported too; not the cheapest service, but worth it.

Sign in to travis-ci.org with your github account, enable travis on your repo, add a .travis.yml file and you are good to go.

Heroku: cloud application platform. I am using it for Pyramid and Plone deployments. They take care of configuring Apache/nginx, firewall, etcetera. You just focus on your code. See http://heroku.com

In .travis.yml you can tell Travis to deploy to Heroku when all is fine. BTW, you can do the same with releasing to PyPI.

Last year I had a slide on using Fabric to release a Plone project. But now you can do that on Heroku with buildpacks. In a nutshell: bin/detect and bin/compile. It is out there and it is being used. See https://github.com/niteoweb/heroku-buildpack-plone It is using RelStorage. Our company website is hosted on Heroku since a few months.

They handle the database, which stays online. When you deploy, the buildout is run (the compile step) and once it is up and answering requests, the old Heroku instance is brought down. So no downtime.

Heroku is free for basic uses. But with Plone you hit the free database row limit after about 100 content items. After that, it costs about 9 dollars until the next limit that is a lot higher. On the free plan, when you have no traffic for an hour, your app is shut down, and then for Plone it will take about a minute for the next request.

We are missing a Plone 5 button on http://buttons.heroku.com. I am working on it.

Heroku forces you into good practices. If a requests takes longer than a minute, it is killed. So you don't keep that page that is taking longer.

Sentry: cloud error reporting. I used to use mailinglogger in Plone, but not anymore. Benefit of Sentry: it is smarter about sending only one email when there are lots of errors. And you see the stacktrace. Easy to set up in a buildout. See http://getsentry.com

Papertrail: cloud log aggregation. Everything in one interface. See https://papertrailapp.com

For most of these, you can choose to run it yourself, instead of depending on third parties.

Watch the video of this talk.

What is the current state of javascript in Plone, version 4.3?

Javascript was always a needed skill for Plone developers. Progressive enhancement: the site works okay without Javascript and works nicer with it. We introduced overlays and other sugar on top of Plone.

My experience the last years is that I have a small project where I use Plone and do a small bit on top. And larger projects, for which I do not use anything from the standard Plone front-end at all. If the project is large enough, this is sensible.

Lazy loading of parts of the page. You do not want to load a thousand comments at once. That can still be done with jQuery and a bit extra on top of Plone.

Problems:

• Page load is too slow.
• With jQuery you end up with ever more spaghetti code, adding bindings to buttons everywhere.

For a project we made a list of requirements:

• full feature solution
• no best of breed solution where you need to combine three or more frameworks and know them all
• good documentation and books
• What I like about Zope is: it teaches me stuff. PHP did not teach me anything. It just did not work. I wrote crappy applications or I was using a crappy framework. Or both. Then Zope and Plone came along. I would learn new stuff, knowing I was learning really useful stuff. So I wanted a good framework, well thought through.
• A framework that was here to stay for a while.

I won't do a comparison, but we chose Angular. Why?

• Full feature frontend framework.
• Developed in 2009 by Google.
• Google is using it for more than a thousand apps internally. Very popular online and in conferences.

Angular does not try to reinvent the wheel.

• Model View Controller. You have a model in Javascript and bind it to your angular template.
• Two way binding: changing the model changes the input, but also if you change an input in a browser, the model is updated.
• Keep the complex code in your Javascript, not in your template.
• Create directives that contain code for your use case, for example for easy bootstrap integration.
• Dependency injection. You write an Angular script, with a function and the function call has getUsersService in it. Then it gets this service (from a file that is already loaded) and you can use it within that function.

BTW: it is cool to edit a css or js file and have the browser reloaded automatically, with grunt or gulp. Really fast development.

Might be nice to keep the good parts of Plone, like permission management, and do the front end in Angular (or a similar framework), where Plone mostly serves up some json.

See https://github.com/tisto/plone.app.angularjs

My personal opinion is that we need a RESTful json api.

Reasons not to use Javascript:

• You might still have users without javascript.
• Search engine optimization (Google cannot crawl data that is loaded by Angular).
• May not be nice for mobile users or for old browsers.
• You need a lot of testing, because a single error may break your complete javascript.

Let's see what we can come up with as Plone community, with Angular or ReactJS or something else. I certainly recommend that you check out Angular.

Watch the video and slides of this talk.

Watch the screencasts shown in the talk: BrowserSync, Two Way Binding, and plone.app.angularjs

This talk is about experimental security indexing.

What is the problem we are trying to solve? Performing operations on the sharing tab can take very long, for large sites. There are complex hierarchies around the problem, the allowedRolesAndUsers index in the portal_catalog. Depending on the number of objects that are affected, a request can timeout or worse.

Local roles can be assigned to any user, stored in __acl_local_roles__ on the context, inherited by default.

For the Plone Intranet Project, we started working on this: Matt Hamilton, Ben Cole, and me.

Various approaches were attempted.

• Using PAS groups to represent groups of permissions or roles. You then assign users to these groups. Can become a lot of groups, that you preferably do not want to see.
• Implementing a show tree as a ZCatalog index: https://github.com/netsight/experimental.localrolesindex Abandoned, because it was too complex at a wrong level.

Current implementation: https://github.com/netsight/experimental.securityindexing

Patches the reindexObjectSecurity method for each content type. A utility stores a shadow tree, mirroring the live site. Stores a hash of the local roles. Make sure the security is only reindexed if the local roles change. Some subscribers to make sure the tree is kept up to date.

• Keep shadow tree up to date.
• Compute hash of local roles.
• Reindex the main object.
• Compute hash of local roles again.
• If the local roles are the same, do nothing more with the children.
• If applicable, do the same for the children, grandchildren, etc.

We did benchmarks, showing that this solution is a lot faster, both for Archetypes and Dexterity.

Next phase is to test it extensively on some real world scenarios and sites, and make sure it meets the workspace requirements for Plone Intranet.

Don't go into the ZMI and add local roles there, or do other stuff that Plone does not know about. Don't clear the allowedRolesAndUsers index.

The buildout extends the Plone 4.3 core development buildout and somehow the speed gain is much less; I don't know yet why that is the case.

If you have a project where you have this problem, try it out, for now on a development instance. You could also try to install the [benchmark] extra, generating benchmark-at and benchmark-dx scripts to create sample data and time it.

Watch the video of this talk.