MaisonBisson

While writing up the draft docs for Joyent’s Container Name Service I leaned heavily on the user stories and use-cases for the feature. It has me realizing that we should consider user stories to be the first draft of the user documentation.

Indeed, consider that well-written docs and user stories have similar qualities: a user, goal, and benefit, in clear language that’s accessible in small, focused chunks.

The CNS docs are now in our core documentation library, and I’m happy that we’ve updated the content management system to support deep linking to individual headings, like this one about adding CNS service tags when creating an instance with the triton CLI.

I’m thinking about this and writing now because Alexandra has joined the team and is adding short screencasts that do more to “show, don’t tell” how to use the features while providing additional context. See this screencast explaining usage with docker, assigning vanity names, and her overview of CNS’ function and purpose. She’s been digging in to the existing documentation, asking questions, and driving a lot of improvements. All that had me considering the source material and the relationship to user stories.

A 50-50 blend of morning glory juice and latex created rubber with maximum bounciness, while a 75-25 mix of latex and morning glory made the most durable material.

It seems they were making bouncy balls for fun and sport. But, to be clear about the ingredients:

Morning glory plants tend to grow near rubber trees, and both plants were considered sacred in several Mesoamerican cultures. Morning glory, for example, was also used in religious ceremonies for its hallucinogenic properties.

From Rachel Kaufman’s reporting on rubber chemistry and industry in the prehistoric Americas.

The following line in a post about the difference between declarative vs. imperative programming caught my attention for the way it echoes product management best practices:

[I]t’s often good not to think of how you want to accomplish a result, but instead what the component should look like in it’s new state.

Of course it does matter how you get to where you’re going, but it’s a whole lot easier if you first focus on aligning everybody on goals and where you’re going.

# Get function list as array
funcs=($(declare -F -p | cut -d " " -f 3))

# parse out functions and non-functions
i=1
declare -a cmdargs
declare -a otherargs
for var in "$@"; do
    if [[ " ${funcs[@]} " =~ " ${var} " ]]; then
        cmdargs[i]=${var}
    else
        otherargs[i]=${var}
    fi

    ((i++))
done

echo ${cmdarg[*]}
echo ${otherargs[*]}