loading words...

Jun 10, 2019 08:55:02

Syrupy API docs.

by @brianball PATRON | 490 words | 391πŸ’Œ

Brian Ball

Total posts: 391πŸ’Œ
Total words: 107882 (431 pages πŸ“„)

Too much syrup in API docs.

Is it just me? 

When I'm trying to understand new concepts, I want them expressed simply.


React components implement a render() method that ... 


Is the word 'that' indicative of backwards writing?


... that takes input data and returns what to display.


( what do display ) - Somebody got lazy here. It's correct, but doesn't reveal the ingredients I'm looking to understand.


We put in some white stuff with eggs and butter and voilΓ‘ the batter is ready.


What's the WHITE STUFF? Sugar? Flour? Baking soda? Baking Powder? Salt? How much of which?


I might rewrite it like this:

You can pass data into the render() method as a string, expression or JavaScript object. 

Data you pass in is wrapped with a global object you can access with this.props.


Summary: Use a labeled placeholder in your component. Pass the data to be displayed in that placeholder with an assignment in the component call. 


Example: You want to dynamically display a person's username.

Provide the HTML with the placeholder in the return statement of your component.

component HelloMessage ( a class that extends React.Component or a function )

return (<div>Hello {this.props.username}</div>)


Don't mix the explanations of dependent concepts.

( I'm not trying to explain JSX here, but it's possible they won't know what it means early in the docs. They'll have to learn it at some point, but not here. )


Call the component with JSX:  ( three examples provided )

<HelloMessage /> Is the shape of the component call without data.

<HelloMessage username="Brian" /> What it looks like when data is passed in.

<HelloMessage username={ username: this.getUserNameFromSession() } />


In your code, you won't be hard-coding "Brian" -- rather, you might have their username in a value passed in from the authentication process like the third example. It uses another function to grab the data. It's then passed in as part of an object that has a label and a function call. That function call's return value is what will be passed through as 'username' to the placeholder.


I'm reading a lot of technical documentation lately. It can be quite confusing when the enthusiast writing the docs tries to convince you how easy it will be. Of course it's easy. You wrote the docs. You had to grok it before you could try to explain it.


Gaining knowledge and experience is not a simple, single step. There are neurons in my brain that fire when I try to think of your concept. They need myelin. That process of my body depositing fatty insulation around these thought receptors takes a little time. It doesn't happen instantly - even if you want it to.


Good documents have lots of explanations. Remember Pictionaryβ„’? I might have to say things 12 different ways before the concept in my mind emerges as an image for you. Then, you just need to match the image with the right word. 

Yipes! Documentation is Not easy.

  • 1

    @brianball this is something that I'm looking forward to trying, to argue with the technical documentation and not just to accept a thing as is they are. Not trying to complain or anything but to eventually provide improvements and constructive criticism. This helps me to better understand what they are constructed in a certain way.

    It seems I feel your pain when I encounter the syntax of arrow functions in Javascript and React.
    let foobar = ( params) => { return someting };

    It feels so unintuitive to read your code with arrow functions. My mind gets a mild pause of when reading code with an arrow function. I guess it just me 'cause I came from some language like Java, c++ and PHP.

    Chris πŸ€”πŸ‡΅πŸ‡­ avatar Chris πŸ€”πŸ‡΅πŸ‡­ | Jun 11, 2019 13:22:45
    • 1

      @chrisdeuda - in React specifically, there are some things that arrow functions allow.

      What's fun to see people do is start to write some code -- ( in a video for example ) -- an before they even finish what they're doing, they start pre-optimizing it. It's hard to watch.

      The arrow functions are cool enough. What's weird is optimizing passing around an object without the colon because the key : value share the same name ( i.e. the key is the object property and you're passing in a variable of the same name, so you shorten it to { state } -- where before it would be { state: state }

      All code is just pattern recognition anyway. I guess the young people need to keep changing it to ensure they have some advantage over the geezers moving forward.

      Brian Ball avatar Brian Ball | Jun 11, 2019 07:09:58
    • 1

      @brianball It seems I've encountered that when I'm reading the ES6 syntax, but I forgot the what's the term they use for that trick. It's a really cool trick but it was a little hard to read if you came from other languages.

      You nailed it I guess the young people need to keep changing it to ensure they have some advantage over the geezers moving forward. .. It seems they call it syntactic sugar. When they have fancy syntax on doing specific things. haha

      Chris πŸ€”πŸ‡΅πŸ‡­ avatar Chris πŸ€”πŸ‡΅πŸ‡­ | Jun 12, 2019 18:51:40
contact: email - twitter / Terms / Privacy