NOTE: In the TL,DR, optimize for clarity and comprehensiveness. The goal is to convey the post with the least amount of friction, especially since ipython/beakers require much more scrolling than blog posts. Make the reader get a correct understanding of the post's takeaway, and the points supporting that takeaway without having to strain through paragraphs and tons of prose. Bullet points are great here, but are up to you. Try to avoid academic paper style abstracts.

  • Having a specific title will help avoid having someone browse posts and only finding vague, similar sounding titles
  • Having an itemized, short, and clear tl,dr will help readers understand your content
  • Setting the reader's context with a motivation section makes someone understand how to judge your choices
  • Visualizations that can stand alone, via legends, labels, and captions are more understandable and powerful

Motivation

#Motivation

NOTE: optimize in this section for context setting, as specifically as you can. For instance, this post is generally a set of standards for work in the repo. The specific motivation is to have least friction to current workflow while being able to painlessly aggregate it later.

The knowledge repo was created to consolidate research work that is currently scattered in emails, blogposts, and presentations, so that people didn't redo their work.

This Section Says Exactly This Takeaway

#This-Section-Says-Exactly-This-Takeaway
Loading output library...
Loading output library...

NOTE: in graphs, optimize for being able to stand alone. When aggregating and putting things in presentations, you won't have to recreate and add code to each plot to make it understandable without the entire post around it. Will it be understandable without several paragraphs?

Putting Big Bold Headers with Clear Takeaways Will Help Us Aggregate Later

#Putting-Big-Bold-Headers-with-Clear-Takeaways-Will-Help-Us-Aggregate-Later

Appendix

#Appendix

Put all the stuff here that is not necessary for supporting the points above. Good place for documentation without distraction.