A few years ago, programmer and writer Bernard Meisler argued that coders write bad software because they're bad writers.
"Most engineers can't write a single coherent sentence, never mind string together a paragraph," he wrote.
So when software engineers write documentation, he reasoned, their incoherent API descriptions infect downstream code by confusing fellow programmers.
Mozilla is planning a fix of sorts. While it cannot teach everyone to write well or end the scourge of impenetrable technical specs, the maker of Firefox and the Rust programming language has teamed up with Google, Microsoft, Samsung and the W3C to consolidate and clarify the web's de facto how-to manual, otherwise known as the Mozilla Developer Network (MDN).
There are, of course, many other online resources documenting web technologies, but 12-year-old MDN – a wiki to which anyone can contribute – is one of the most widely used, visited by six million designers and developers every month.
Mozilla and its associates would like to see MDN become even more popular, by making it the one web development manual to rule them all, with the help of Microsoft and Google.
Ali Spivak, head of developer ecosystems at Mozilla, told The Register in a phone interview on Wednesday that Google, Microsoft and others have been contributing to MDN informally. A few months ago, the various parties decided to formalize the relationship through a Product Advisory Board, she said.
"One of the side benefits of a Product Advisory Board and more input from others, I hope, is that it will enable us to target our resources more effectively," said Spivak.
Y'know CSS was to kill off HTML table layout? Well, second time's a charm: Meet CSS GridREAD MORE
She cited the relatively recent debut of CSS Grid support in various browsers as an instance where more coordinated communication between the various vendors might have provided better information for developers.
As a result of the tie-up, Microsoft, maker of Edge and Internet Explorer, says it's going "all-in" to support MDN as the locus of web standards docs. The Windows giant intends to redirect its API reference library to MDN.
"Developers shouldn’t have to chase down API documentation across standards bodies, browser vendors, and third parties – there should be a single, canonical source which is community-maintained and supported by all major vendors," said Erika Doyle Navara, senior content developer at Microsoft, in a blog post.
Google hasn't gone quite so far, but says it's excited to work with the group to make MDN the best, most current documentation for web devs.
MDN already scores well in surveys, topping Slashdata's recent survey in the documentation category.
"This will help us make it even better," said Spivak.