The week we talk about the new Open Web Docs initiative and the future of MDN.
Documentation. You can treat it as a dictionary or reference manual that you look up things in when you get stuck during your day-to-day work OR (and this is where things get interesting) you can immerse yourself in a subject, domain, or technology by deeply and purposefully consuming its manuals cover-to-cover to develop expertise, not just passing familiarity.
In this episode we pull in perspectives and anecdotes from beginners and veterans alike to understand the impact of RTFM deeply. Also Sweet Filepath O’ Mine?!?!
If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an ARCHITECTURE document next to README and CONTRIBUTING. Before going into the details of why and how, I want to emphasize that this is not another “docs are good, write more docs” advice. I am pretty sloppy about documentation, and, eg, I often use just “simplify” as a commit message. Nonetheless, I feel strongly about the issue, even to the point of pestering you:-)
The author points to rust-analyzer as a good example.
I dig this effort to decouple web documentation from a “single vendor or organization.” 👏
Open Web Docs was created to ensure the long-term health of web platform documentation on de facto standard resources like MDN Web Docs, independently of any single vendor or organization. Through full-time staff, community management, and our network of partner organizations, we enable these resources to better maintain and sustain documentation of core web platform technologies. Rather than create new documentation sites, Open Web Docs is committed to improving existing platforms through our contributions.
Wanna get involved? Check out the high-level goals they have laid out.
GitHub open sourced this long-lived private project. Learn about the why and how in this post…
Last week we open sourced all of GitHub’s product documentation, along with the Node.js web application that powers it. Check out our new public repository at github.com/github/docs.
This post tells the story of why we wanted to open source the docs, what tools we built and open sourced along the way, and how we worked to make the project welcoming to external contributors.
Rina Jensen shares more details on the future of MDN Web Docs in this post on Mozilla Hacks.
First we want to be clear, MDN is not going away. The core engineering team will continue to run the MDN site and Mozilla will continue to develop the platform.
However, because of Mozilla’s restructuring, we have had to scale back our overall investment in developer outreach, including MDN. Our Co-Founder and CEO Mitchell Baker outlines the reasons why here. As a result, we will be pausing support for DevRel sponsorship, Hacks blog and Tech Speakers. The other areas we have had to scale back on staffing and programs include: Mozilla developer programs, developer events and advocacy, and our MDN tech writing.
Have you heard of the GitHub Arctic Code Vault? If not, the goal of GitHub Arctic Code Vault is to preserve open source software for future generations. Which means we need thorough docs describing how the world makes and uses software. Which I find completely fascinating!
We are now also opening up the initial compilation of Tech Tree resources to community input. Inspired by the Long Now Foundation’s Manual for Civilization, the Tech Tree is a collection of technical works which document and explain the layers of technology on which today’s open-source software relies, along with works included to provide additional cultural context for the Arctic Code Vault.
What follows, which we call the Tech Tree, is a selection of works intended to describe how the world makes and uses software today, as well as an overview of how computers work and the foundational technologies required to make and use computers. The purpose of the GitHub Archive Program is to preserve open source software for future generations. This implies also preserving the knowledge of other technologies on which open-source software runs, along with a depiction of the open-source movement which brought this software into being.
1️⃣ Value contributions to documentation just as much as code contributions
2️⃣ Put documentation and code in the same project repo
3️⃣ Make documentation a requirement for a merge or release milestone
4️⃣ Have a consistent contribution process for code and documentation
5️⃣ Have well-documented processes for contributing to documentation
That’s the TL;DR, but each of these is expanded upon in the article.
Looks interesting. Would you use this?
Searches a curated subset of the web: official docs and community-driven sources. No JS, cookies, tracking, external requests or data collecting.
There’s lots of feedback from Rakhim (the creator) and commentary on Lobsters too.
Are you striving to create a culture of written comms? Maarten Claes writes…
More and more people are being exposed to working remotely. One of the key factors for success in a remote workplace is a culture of written communication. It’s not always obvious how to create such a culture, and it takes at least some level of discipline from the people involved to make it a habit.
I’ve worked with mostly remote teams over the past three years. Here are a few of my observations on what helped cultivate such a culture.
I like Git commit messages. Used well, I think they’re one of the most powerful tools available to document a codebase over its lifetime. I’d like to illustrate that by showing you my favourite ever Git commit.
6-ish paragraphs of explanation for a single whitespace change in the code.
This article starts out like a bit of false advertising:
It doesn’t matter how good your software is, because if the documentation is not good enough, people will not use it.
People tell us that about documentation all the time. Come on, now. Get to the good stuff!
In this article I will explain how you can make your documentation better, not by working harder at it, but by doing it the right way. The right way is the easier way - easier to write, and easier to maintain.
OK, I’m listening. I’m listening.
Documentation needs to include and be structured around its four different functions: tutorials, how-to guides, explanation and technical reference. Each of them requires a distinct mode of writing.
Pay dirt! 🙌
This is an absolute must-read on the four different kinds of docs and how to effectively execute on each.
readme-md-generator is able to read your environment (package.json, git config…) to suggest you default answers during the README.md creation process
Nice to see it using All Contributors.
Twilio uses a custom-made, 8-bit RPG game to teach developers their APIs, both online and at events like Superclass and Twilio Signal. Created by Kevin Whinnery, TwilioQuest is a premier example of how to educate developers without putting them to sleep.
“Younger generations of technologists […] have grown up collecting loot and gaining XP”
This is basically an API for the (excellent looking) Mermaid.
Safia, Nick, Jerod, and Chris get together to talk about documentation. Documentation is essential in our work but it can be difficult to get buy in. The crew talks about how you can get others to care about it in your organization, tools that make documentation easier, and some examples of companies doing it right.
Resources to help you get started quickly with Apollo.
Whether you’re experimenting with GraphQL or running Apollo in production, we want to make every developer’s journey as smooth as possible. This is why we’re releasing two new resources to help you along the way: the GraphQL Glossary and an FAQ guide! 🚀
Do you have documentation? Do you have a documentation content strategy? No?!!
If you want to create guides for your software, having a solid content strategy can help you write useful content. This article will walk you through how to develop that strategy, whether you’re an engineer or a technical writer, new to writing documentation or just looking to get more strategic about it.
The UIengine is a tool to build pattern libraries and documentation for design systems. It helps designer and developers to work closely together and offers features to boost their productivity.
Most of the existing tools focussed on the component development, but lacked ways to also provide good documentation. Some were limited to using a specific templating language or framework, which was suboptimal for me: As a freelancer I am working on many projects and each one has its own set of constraints and requirements. I wanted to build a tool with an open source license, which I could use and extend with every project I work on.
Docz’ high-level principles give you an idea of what they’re all about:
- Zero config and easy. No unnecessary build steps with confusing setups.
- Blazing fast. Always use the fastest things to build our tools.
- Easy to customize. Create something that will be easy to use and customize.
- MDX Based. Have the best standard to write documents.
- Pluggable. Plugins are the best choice when you need to be custom and flexible.
Watch the demo video on the homepage to see just how nice this tool is to use.
From Kelly Burke:
You can use this web app to write and sell books on your own domain. We use it for our own book, which teaches you how to build the app from scratch: https://builderbook.org/book
Pretty cool. Writing your documentation or book in Mardown is amazing for a lot of writers. The reading experience on the web could be a bit better, but the app comes with all the third-party integrations you’d want to sell your book.
Unlike the guide which walks you through building a Vue app in story form, the cookbook is all about focused examples of how to accomplish specific goals with the framework.
This is an excellent addition to the compendium of documentation in support of the project, and one that’s worthy of emulation once your framework has a base set of docs that are solid.
Facebook announced Docusaurus to more easily maintain open source documentation websites.
We created Docusaurus for the following reasons:
- To put the focus on writing good documentation instead of worrying about the infrastructure of a website.
- To provide features that many of our open source websites need like blog support, search and versioning.
- To make it easy to push updates, new features, and bug fixes to everyone all at once.
And, finally, to provide a consistent look and feel across our all our open source projects.
Will Norris (Engineering Manager at Google’s Open Source office) joined the show to talk about their new release of the Google Open Source website as well as the release of Google’s internal documentation on how they do open source. Nearly 70 pages of documentation have been made public under creative commons license for the world to use. We talked about the backstory of Google’s Open Source office, their philosophy on OSS, their involvement in the TODO group, and much more.