Restructured Text and Sphinx

Restructured text is the broadly-supported approach to documenting Python code. It's basically a set of conventions to format text files through the use of punctuation, using the same basic approach that many people have used in contexts like email and readme files. Restructured Text basically formalized these hokey conventions into a slightly hokey set of rules that can be used to put together readable, formatted text files, which can be processed using utilities like Sphinx:

http://www.sphinx-doc.org/en/stable/

Sphinx is a documentation engine, developed to generate formatted documentation of source code. It is mainly designed to support Python projects, and it has cool features for documentation of Phython code. It can pull in structured comments (called Docstrings) directly from source code, using directives like automodule, autoclass and autofunction. Most importantly, it has the ability to assemble documents into a single internally-linked document structure, using things like toctree. Here's an example of an RST file for Sphinx:

.. Note This is a template for meeting notes.

  Update this as appropriate.

.. header:: Notes: Stephen

.. meta-data fields for Sphinx:

.. index:: template

.. sectionauthor:: Stephen 

.. Substitutions here:

.. |reST| replace:: reStructuredText

.. image:: ./image.png

.. sidebar:: callouts

    Include callouts here

Template: Notes

==============================================

Topic:

-------

#. Topic 1

#. Topic 2

#. Topic 3

This file is entitled "Template: Notes". It's got a lot of comments at the beginning, including the header and sectionauthor field. It contains a substitution directive, which lets you type "reST" instead of "reStructuredText". It inserts an image into the document and has a sidebar comment. When this is rendered in Sphinx, it will all get assembled into a document format of your choice: html, pdf or even ePub. 

Lately, I've discovered that RST/Sphinx is actually a pretty good answer to note taking applications like Microsoft OneNote and Evernote. RST files are lightweight and easy to read, and when assembled by Sphinx, they constitute a highly readable notebook that can be used to track personal notes over time (including searching and indexing.

I'd recommend taking a look at RST and Sphinx. The Sphinx engine is available for download from here: http://www.sphinx-doc.org/en/stable/. I've included a cheat-sheet of my favorite Sphinx terms below:

Marissa Mayer and the Fight to Save Yahoo! - Nicholas Carlson

Of the accounts of Silicon Valley business adventures that I have read this year, this is without a doubt the most fascinating. I have come away with a new impression of Marissa Mayer's efforts to save Yahoo!. I had regarded Marissa's tenure to be at some level, a refutation of the Google approach--one which seems to work well in a company that already has an unprecedented first mover advantage and is wondering what to do with all of the money that it keeps accumulating, but doesn't really work in a competitive market. My new appraisal is more complex: she actually did a lot for the company, but far from enough. 

More than any other company, Yahoo's history traces that of the Internet, from its early days as a "Jerry and David's Guide to the World Wide Web" in 1994, it has been a company focused on bringing the Internet to middle America. In its early days, 'The Internet' constituted a focused goal in and of itself, but as middle america came to embrace the Internet and our grandparents became adept at social media, nobody really needed a Yahoo to explain it to them. After a lot of fascinating history of early Internet companies including a failed takeover by Microsoft, Nicholas Carlson sets the stage for Marissa's messiah-like entrance in 2012 and leadership until its eventual acquisition by Verizon which wrapped up earlier this year. 

Marissa sought to bring Yahoo! forward into the modern Internet era. She made changes to the workplace that made Yahoo! more closely resemble a modern Silicon Valley company, including all those double-edged perks which make it so hard to stay away from work. I suppose that if Yahoo! had, in fact, come up with something totally revolutionary like an 'iPad' or a cloud computing platform, it might still be independent and we would all be singing Marissa's praises still. Steve Jobs breathed new life into Apple after his famous return in 1997, but this is because Steve's are amazing. Yahoo! did come out with impressive news, sports and entertainment services, acquired Tumblr and generally got better. However, no products were compelling enough to make Yahoo! the That! company, unless 'That!' is peanut butter, spread to thin or perhaps the world's largest data-breech company, including 500*10^6 user accounts in 2014. Without any deep insight, this appears to have been a legacy of Yahoo's continuous history from the insecure 90s, when security was not generally taken seriously, rather than any of Marissa's actions, but it does seem to have been the iceberg that struck the Titanic. 

Carlson provides an engrossing cautionary tale of a company that just couldn't decide what it wanted to be and ended up as nothing in the end. He does a great job of placing you in the room:

"It was Thursday: November 7, 2013. Everyone in the company was waiting for Mayer to say something to remind them that she was the CEO who was finally going to restore Yahoo to its rightful place in the Internet industry.

Mayer took a breath. She said hello to everyone. She reminded them of the meeting’s confidentiality. She said she looked through their questions and she had something she wanted to read. It had been a book in her hands, after all. A children’s book.
She began to read.

"Bobbie had a nickel all his very own. Should he buy some candy or an ice cream cone?"
Mayer held the book up, to show the employees the illustrations.
"Should he buy a bubble pipe? Or a boat of wood?"
Another illustration.
"Maybe, though, a little truck would be the best of all!"
Employees in URLs exchanged looks. At their desks, employees in remote offices grew confused.
What was Mayer doing?
She kept reading.
"Bobbie sat and wondered, Bobbie sat and thought. What would be the NICEST thing a nickel ever bought?"

Mayer seemed to skip a few pages. She read, with a slight agitation in her voice:
"He might buy a bean bag or a top to spin. He might buy a pin-wheel to give to little Brother. Or should he buy, thought Bobbie, a little pencil box?"

Mayer seemed to be reading with real frustration now, as though all of the anger and confusion in the room would just go away if everyone would just understand the story she was reading out loud.

“Bobbie thought—and suddenly a bright idea came,” Mayer read, reaching the book’s last pages.
"He spent his nickel just like this - - - -"
Mayer held the book up to show its last illustration. It was a drawing of a little red-haired boy riding a merry-go-round pony.
Hardly anyone could see the page.
No one understood what Mayer was trying to say.

Perhaps she should have read Marie Kondo's The Life-Changing Magic of Tidying Up: The Japanese Art of Decluttering and Organizing.

Book review: Brain on Fire

Brain on Fire - Susannah Cahalan

• This was an entertaining first-person account of the author's experience of a rare autoimmune disease, anti-NMDA receptor encephalitis. This is one of the most well-researched first person medical narrative that I've encountered. Ito stood out from other works in this limited genre in its extensive inclusion of personal details, obtained retrospectively by the author from her own medical record. She manages to provide a large amount of technical details about the disease without interrupting the emotional thread of this narrative. 
• This book brought back personal memories for me, as I found myself recalling a guest seminar on anti-NMDA receptor encephalitis from my days in graduate school. This provided me with a new perspective on this illness. 
• After Googling this title, it looks like it's being made into a movie.

Work Rules - Laszlo Bock

This book describes the general approach to HR followed by Google and the ideals of the prototypical open Silicon Valley company. There's no way to guarantee that your company will deliver a valuable creative product, especially at the level of Google. However, there are some steps companies can take to make it more likely that this will happen.

When you get down to it, we have to ask what we are working for. When you have filled all of the lower tiers on the pyramid, what is it you'd choose to fill the upper tiers? There really are many different answers to this question: create works of art, build bridges, party all the time. The answer depends on the type of person you are, and that is where Work Rules come into play. These are what Google has identified as a general process for making sure that your company can deliver something great for the greater good of society, while it works to fulfill the personal and spiritual needs of the employees who make up your company. With that in mind, here are the 10 Steps that you can do to change your workplace tomorrow:

1. Give your work meaning
   • Make work more than a means to an ends
   • Connect it to an idea that transcends the day-to-day while also relating to your everyday work
   • Whatever you're doing matters to someone
2. Trust your people
   • If you believe that human beings are fundamentally good, then act like it
3. Hire people better than you
   • It's always an error to compromise on hiring quality
   • Hire by committee
   • Setup standards in advance
   • The proof that you're doing well is that 9 out of 10 hires are better than you are
4. Don't confuse development with managing performance
   • Have developmental conversations all the time and separate them from performance (in space and time)
   • The conversation about performance should be about outcomes
5. Focus on the 2 tails
   • Put your best people under a microscope and identify their best traits
   • Find the most specific slice of expertise and use them as examples & teachers
6. Be frugal and generous
   
   • Bring in local vendors. 
   • Focus on the most human moments
7. Pay unfairly
   • Performance is an exponential curve
8. Nudge
   • Subtly change behavior
   • How much you save is the biggest determinant of your personal wealth.. tweaking your savings rates by small amounts can have a huge impact on your wealth at retirement
   • Look around at how your environment is nudging you right now
9. Manage the rising expectations
   • Change requires adaptation
10. Enjoy (then go back to #1 and start again)
    • Workplace improvement is a constant improvement process
    • Learn from your experiments and try again

centithread

centithread - an email thread with > 100 responses

Please forward!

Moonwalking with Einstein by Joshua Foer

This book was a unique hybrid of personal narrative and self-help book, in which Josh leads you through his personal experiences in the realm of extreme memory sports while simultaneously explaining the memory tricks he learned. I found it to be a unique account in the level of detail it provided into what are normally internal thought processes. Think of how fleeting an experience it is to actually piece together a memory, and yet within its moment, clearly defined. 

While I was recalling this, I thought back to my own experience in reading Josh's personal account of his induction into the memory club, whose name escapes me now, in which he is required to down two pints and then recall an arbitrary list of facts that he had just learned. I remember thinking at the time that it was nearly impossible he would be able to recall the entire experience of learning the list, downing the beers and then trying to recall the list (even failing for the first time). In attempting to recount my feelings about this at the time, I remembered that I had been reading this book as an ebook on my phone, while sitting in bed. 

OK, obviously nobody can recall in that level of detail, and the whole remembering of forgetting poses certain logical problems. Nonetheless it seems a realistic and useful account. The mental tricks are genuinely useful and worth applying. I'll see if I can use them to remember folks' names. 

Where crates and barrels come from

Bicycle Helmets

Get Outlook for Android

The building blocks of life

Titanic thoughts

Get Outlook for Android

Model Hanne Gaby Odiele on What It Means to Be Intersex—And Why She's Going Public

http://www.vogue.com/article/hanne-gaby-odiele-model-intersex-interview

Schwerpunkt

Schwerpunkt - main point, main target; point upon which the most effort is concentrated (e.g. during an attack). From German Schwerpunkt ‎("main focus, focal point, center of gravity"), from schwer ‎("hard, weighty") + Punkt ‎("point").

Top 10 Beers of 2016

American Warlord

American Warlord by Johnny Dwyer is the story of an American teenager who eventually came to be the brutal dictator of Liberia. It's an amazing story, not so much for it's uniqueness as its banality. The horrific atrocities perpetrated by Chuckie Taylor in his role as head of Liberia's 'Anti-Terrorism Force' (ATF) appear in this context almost as an extreme extension of gang violence and are later the subject of his rap lyrics during his exile in Trinidad to avoid prosecution. The author's unobtrusive narrative style remains an engrossing personal story throughout, albeit the sheer volume of horrific torture scenes were hard to get through. The final segment of this seemingly unlikely story ends in a Miami courtroom where Chuckie is finally confronted with his crimes and the victims who suffered because of them.

• Available on Amazon