HomeSectionsAboutMerch

Brain dump

So......I've been thinking about things. Some of those things are "why doesn't PHP have a general website other than the manual" and also "supporting the manual is terrible".

This is a brain dump of some of those thoughts, as apparently I am finding it difficult to write cohesive documents.

Problem: editing any doc format other than markdown is more effort than most people can muster

As much as I use the PHP manual, and would like other people to contribute to it, I find it hard to either edit it myself, or tell people 'hey you should edit it!' as it's.....just a bit annoying.

Solution: make most of the content be in markdown.

Problem: conversations don't scale

Conversations online are kind of terrible...in particular conversations about curating content are inevitably terrible.

But also as the size of any community grows, the chances that at least one of the people in it is annoying also grows. It is not possible to implement a code of conduct that prevents assholes from being assholes, without a huge ongoing amount of effort. But it is possible to deliberately keep communities (and so communication) separate, so that an asshole in one particular community, only affects that community, rather than borking a whole project.

Solution: avoid the need to have conversations scale. It's better to have only a few people who are interested in a particular topic be in charge of that topic, rather than them having to take feedback from everyone involved.

Problem: Managing a website is boring

Solution: separate out the running the website from the content creation. In particular, people are fine with creating file in markdown, or other simple formats. If I can tell someone, "what you just gave a talk about was really great, you should write it as a document and I'll host it for you", that's more like to have something useful created, than if they have to deploy a whole website.

Problem: People grow bored of managing content

It's a common pattern for people to be enthusiastic about the tech they use, but then when they switch to working mostly in another language, it's probable they will lose enthusiasm for the first tech.

This becomes a problem when docuements need updating

Solution: Make it easy to fork content, and have the website be able to switch to the new version.

Problem: sites rot, sites diverge

A couple of the websites that I used to visit, including pretty much all Java documentation, seems to be vanishing from the net. Without the source of that content, it's not possible for other people to host that content.

Separately, the needs of the Symfony/Laravel people might be quite different from the needs of people who don't use those frameworks. They would want some content on a general PHP website that would be inappropriate for non-Symfony/Laravel people, and vice-versa.

Solution: Have all the content be distributed, in re-usable formats, it means that either when I grow bored of running this site, or people decide I'm doing a shite job, they can make a new site, that focuses on their needs more specifically, rather than trying to persuade me to keep an individual site running.

btw at some point I'll consider giving control over subdomains on this site (e.g. symfony.phpopendocs.com) to people who ask nicely for them.