WingNews logo WingNews GitHub [2]

wbamberg's comments

wbamberg | 2 years ago | on: Perilous Joy: George Eliot and the marriage question

It is a reference to the closing lines of Middlemarch:

"But the effect of her being on those around her was incalculably diffusive: for the growing good of the world is partly dependent on unhistoric acts; and that things are not so ill with you and me as they might have been is half owing to the number who lived faithfully a hidden life, and rest in unvisited tombs."

wbamberg | 3 years ago | on: MDN converted to Markdown

I'm not sure exactly what you're asking about, but if it's our use of `var` in code examples, we had a big project this summer to eradicate `var` in favour of `const` and `let`.

This started out as a project for the Writing Day at the Write the Docs Portland conference (https://openwebdocs.org/content/posts/writing-day-wtd-portla...). It then continued as a much bigger thing: https://openwebdocs.org/content/posts/2022-q3-report/#modern.... Much of the work was done by volunteers, and it's a great example of the kind of project that I don't think would have been possible back when MDN content was in a Wiki.

If you're asking about whether we should un-recommend `var` more strongly: looking at the page for `var` (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...) - well, maybe you are right...

wbamberg | 3 years ago | on: MDN converted to Markdown

Sorry, I didn't intend to misrepresent, but yes, there is a fuller story here of course.

Before 2020, MDN was in a Wiki and editors could use a WYSIWYG interface, which was OK for relatively simple edits although for more involved stuff we often had to resort to the raw HTML source (and even for simple edits, the editor would often not generate the markup you might have expected). Being in a Wiki meant there was no pre-publication review process, and it was very hard to make systematic improvements to the content. You couldn't, for instance, create a single pull request updating dozens of files and review them all together. Whether that was sustainable, or whether overall quality just gradually declined - well, it was certainly really hard to maintain.

At the end of 2020 MDN content moved into GitHub, I think that's enabled us to make large-scale improvements to the content that wouldn't have been practical before, as well as to have a review process to ratchet up overall quality.

But this move also meant the WYSIWYG editor went away, and everyone was faced with editing the raw HTML source, all the time, and I really don't think that was a sustainable situation. We could I suppose have revived something like the WYSIWYG editor, but I think switching to a simpler source format was a better option.

wbamberg | 3 years ago | on: Markdown, Asciidoc, or reStructuredText – a tale of docs-as-code

Last year we changed the source format for MDN from some extremely messy, WYSIWYG-authored HTML to something that would be easier for authors to use. We considered Asciidoc and reST, and despite its limitations, we chose Markdown (GFM specifically) for two reasons:

1. We get a _lot_ of casual contributors to MDN: about 180-200 unique contributors/month, most of whom we never see again. Almost all of them can contribute much more easily with Markdown than with anything else. Many of these people are unlikely to put even an half an hour into learning a new syntax.

2. Markdown has great tooling support. For example, if we want to run Prettier over our embedded code samples, it's really easy if we are in Markdown. If we are in Markdown we will get nice formatting just about everywhere, including GitHub of course and most people's editors.

One thing that made the choice easier for us is that MDN's a very mature doc site, so we had a very good idea of which Markdown limitations were likely to be a problem for us.

If you're interested, we blogged about this project: https://openwebdocs.org/content/posts/markdown-conversion/.

wbamberg | 4 years ago | on: What makes a great opening line?

"The cradle rocks above an abyss, and common sense tells us that our existence is but a brief crack of light between two eternities of darkness."

wbamberg | 4 years ago | on: MDN Plus

> Elsewhere in this thread is a link to a separate organization called "OpenWebDocs," which appears to be an outside consortium that contributes to MDN.

Yes, that's what Open Web Docs is. It's funded by individual and corporate contributions, through https://opencollective.com/open-web-docs/. The money goes to pay writers (currently 2 full time, but we are hiring 2 more) to create and maintain independent open web documentation ("open" in the sense of accessible to everyone, "independent" in the sense that it shouldn't represent any one company's view). Currently our work is pretty much entirely focused on MDN, although that's not necessarily going to be the only thing we ever work on. Our 2021 high-level goals: https://github.com/openwebdocs/project/blob/main/2021-goals.... .

page 1