Open source project documentation on Github and – a year later

After having Plone CMS‘s   Plone Developer Documentation (collective.developermanual project) hosted on Github a year or so how do we fare?

1. Some stats

  • 45 contributors
  • At least one commit per week
  • The most popular of Plone community repositories (plone + collective). Plone community has more than 400 repositories on Github alone.

Six month progress – no clear visitor growth 🙁 (background: Plone does not compete with WordPress et. al. as it mainly solves “big intranet” problems which are not that common)

People don’t work during weekends.

Google, and bring us the visitors.

Troubleshooting is pretty popular with Plone… 🙁

Plone is utterly popular in Brazil.

Long live Firefox. As a side-note Alexander Limi, the guy who did the original praised design of Plone UI, does Firefox UI design nowadays.

We must be attracting a lot of non-Plone developers, because everyone knows Plone developers run OSX or Linux… and who confesses to be this FreeBSD guy?

2. Lessons learnt

  • Plone, Zope and buildout should give better error messages so people would not need to visit troubleshooting sections
  • Better Hello world tutorials still needed (this is not based on analytics, but the sad state of the authors…)
  • and continuous documentation deployment (is there official term akin continuous integration) kicks ass – you can forget the documentation release process, because it is so automatic and just works
  • Edit backlinks in the documentation have proven to be succesful. When you are reading the documentation you can fix the errors in the matter of seconds. Github’s web editor gives wiki-like pace.
  • Github’s fork and edit even better than wiki as non-core editors will generate pull requests and you have a tool and a process to manage those changes

Ps. Also read this interesting reddit thread about history of Plone, Zope and Python

\"\" Subscribe to RSS feed Follow me on Twitter Follow me on Facebook Follow me Google+

Working around buildout server down problems

Plone installations may refer to external HTTP hosted files in buildout.cfg. Things go bad when those servers are down, breaking your development and maintenance workflows. Like today: buildout extends = line cannot reach the servers ( where the version pin down definition file, one telling what known good set (KGS) of components your Plone version needs. Even though if the distribution server is up ( buildout fails badly with very unfriendly error message.

IOError: [Errno socket error] [Errno 60] Operation timed out

(It doesn’t bother to tell that the server which is down is You need to figure out this by running bin/buildout -D and manually inspect the callstack using Python pdb debugger. What a pain.)

Unified installer based installations do not have this problems as all files are local and internet connection is not required to run buildout.

You can work around your buildout issues by manually downloading required extends files from Plone UnifiedInstaller source code base on Github. Just choose correct branch for your Plone version.


wget --no-check-certificate
wget --no-check-certificate  
wget --no-check-certificate

Edit versions.cfg, make pin down references local

extends =

Make sure your buildout.cfg referes to local versions.cfg

extends =

Also you might need to whitelist allowed download hosts in buildout.cfg. If this list is not comprehensive contribute your fixes here.

allow-hosts =
#    *

Run buildout. Now it should churn happily forward.

\"\" Subscribe to RSS feed Follow me on Twitter Follow me on Facebook Follow me Google+

What’s wrong with UNIX people?

From #zsh @

<xxx> I wouldn't ever want to position a cursor using a mouse.
      not even in an editor. a mouse has its uses.
      but that isn't one of them.
<yyy> yes i agree

(yes… it has been taken out of the context, but the message is pretty clear)

I don’t want to flame here, but the argument that one should not position a cursor using a mouse reflects either total 1) ignorance 2) stupidy 3) lack of vision. What do you think all normal 99,9999% users out there would like to do?

This attitude of UNIX community holds back the technology and usability. As long this kind of visionless, all good technology was invented in 70s technology mindset stays around, UNIX command line and shell cannot really progress. And it hasn’t. No mouse positioning. No tooltips for commands. Not even a way to copy file to local from the remote shell.

Should one compare this kind of communities to ultra-orthodox religious communities? All change is bad, you are bad, do like the grandpa says?

The correct answer is that

  • It’s natural to position cursor with mouse
  • People do it with all other programs out there, including other single line text widgets
  • There is no excuse or technical reason why one shouldn’t be able to do it in a shell
  • If the software stack and terminals don’t support it then we should fix them and update them to reflect the modern human interface paradigms

and you can have cursor positioning by mouse support for zsh.


\"\" Subscribe to RSS feed Follow me on Twitter Follow me on Facebook Follow me Google+