Top 29 Developer Docs

Rodrigo Pombo — Mon, 20 Jul 2020 01:04:13 +0000

Sorry for the clickbaity title. The long version should be: "A list of the 29 most mentioned projects on two twitter threads (with 1066 replies) about great developer docs."

These are the threads:

Adam Wathan

@adamwathan

What open source projects have the best docs?

11:59 AM - 05 May 2020

102 839

Dan Abramov

@dan_abramov

Drop links to your favorite docs. And what you like about them.

19:39 PM - 08 Jul 2020

80 638

Don't expect rigorosity. The list is obviously biased in favor of the projects used by the audience of the threads. Also, Adam asked for open source projects.

The top 29 developer docs are:

Shameless plug, I made this list because I'm working on an open-source toolset for building dev docs (among other things), and I was looking for good practices and patterns.

CSS Dragon Illusion

Rodrigo Pombo — Thu, 23 Jan 2020 14:57:24 +0000

The dragon illusion built with CSS:

About React Suspense and Concurrent Mode

Rodrigo Pombo — Sat, 13 Apr 2019 22:14:21 +0000

The next big things on the React roadmap are Concurrent Mode and Suspense.
They are related and complement each other, so people sometimes mix them up. But they represent very different concepts.

Concurrent Mode

To understand Concurrent Mode think about priorities.

Without Concurrent Mode, when React starts rendering something it keeps rendering it until it finishes.

With Concurrent Mode, React will keep an eye on other things that need to be done, and if there's something with a higher priority it will pause what's rendering and let the other thing finish first. That "other thing" could be:

something the browser needs to do
another update that React needs to render
any other task from other libraries or the app's code

import {
  useState,
  takeYourTimeToRenderThisUpdate,
  iNeedThisUpdateAsSoonAsPossible
} from "fictitious-react";

function SlowButLowPriorityComponent() {
  const [someData, changeData] = useState(0);
  return (
    <div>
      <BigComponentThatTakesVeryLongToRender someProp={someData} />
      <button
        onClick={() => {
          takeYourTimeToRenderThisUpdate(() =>
            changeData(prevData => prevData + 1)
          );
        }}
      >
        Expensive but low priority change
      </button>
    </div>
  );
}

function FastAndHighPriorityComponent() {
  const [someData, changeData] = useState(0);
  return (
    <div>
      <SmallComponentThatRendersFast someProp={someData} />
      <button
        onClick={() => {
          iNeedThisUpdateAsSoonAsPossible(() =>
            changeData(prevData => prevData + 1)
          );
        }}
      >
        Fast and high priority change
      </button>
    </div>
  );
}

function App() {
  return (
    <div>
      <SlowButLowPriorityComponent />
      <FastAndHighPriorityComponent />
    </div>
  );
}

// If the user clicks first the SlowButLowPriorityComponent button
// and then the FastAndHighPriorityComponent button
// React will stop rendering SlowButLowPriorityComponent
// and finish rendering FastAndHighPriorityComponent (with its new state) first
// only then it will continue with the SlowButLowPriorityComponent update

You won't need to explicitly set the priority for each update, if you don't React will try to guess the right one.

Suspense

For Suspense think about waiting.

Without Suspense, if your component needs to wait for any dependency (for example, if it depends on some data that needs to fetch from a server) you need to add some state to keep track of the pending dependency, render something while the dependency is pending, and update the state when the dependency is ready.

With Suspense, your component will be able to tell React "Hey React, I don't have all the things I need to be rendered, but I'll let you know when you can try to render me again". Your component won't need to keep extra state or to decide what to render while waiting.

import {
  dontRenderMeUntilThisIsReady,
  Suspense as TryRenderTheseChildren
} from "fictitious-react";
import getMyDependency from "fictitious-dependency-fetcher";

function ComponentThatDependsOnSomething(props) {
  const dependency = dontRenderMeUntilThisIsReady(
    getMyDependency(props.dependencyId)
  );
  return <h1>{dependency.data}</h1>;
}

function App(props) {
  return (
    <TryRenderTheseChildren andIfTheyAreNotReadyRenderThis={<ImTheFallback />}>
      <ComponentThatDependsOnSomething dependencyId={1} />
      <ComponentThatDependsOnSomething dependencyId={2} />
    </TryRenderTheseChildren>
  );
}

And Now for Something Completely Different

I'm at the Amsterdam airport, after #ReactAmsterdam, waiting for my delayed flight, looking at these drawings by Escher, and writing a post that makes an analogy of me writing a post while waiting for my delayed flight.