Wednesday, June 15, 2016

Interview with Bryan Beecham about Pairing w/me the first time

I put a interview Maaret recorded with Bryan Beecham online yesterday.
It's about the first time Bryan paired with me using Strong-Style Pairing.

Here's the video:

and the Transcript:

 So the first time i met llewellyn I was in a session at an agile conference. They were talking about a developer and tester pairing and the benefits of that and it was a great session and the really cool thing was that it was very hands on so I ended up pairing at a table and I had this guy. This guy there with like kinda a little cocky he's got blue hair and I'm pairing with him. And I'm like great, I'll learn. I know how to code a bit... but we are using eclipse (i think) and I don't know eclipse that well... and he asked me that, maybe he noticed my hesitation and he said how well do you know this IDE?
 and I said "ah, it's not my thing"
 and he said "that's ok, because I'm going to tell you what to type."
   and I thought maybe he thinks I'm new to pair programming or something and I don't know about this but no, I was in for a whole new world of understanding because the person, who turned out to be llewellyn, introduced me to some, I guess now it's been modified to strong pairing which has some other meanings to it, but he told me what to do and told me what to type and when you think  
 oh yeah, type something very high high level, but no he was telling me on a very low level of type this word. press enter press semicolon you need a curly brace there and I was not allowed to use the mouse it's like no, no no no it's
 alt+r for that
and word by word, but I'm like 'keep it cool' 'keep it cool' because inside i'm about to boil over and just be furious, right, but then I noticed something was happening.

  I was noticing that I started to know what extract method was I started to pickup on somethings I started to understand the syntax better and his language started changing as this happened and he started talking at a more abstract level and his instructions got moved to a higher level and we were actually picking up speed and I was like 'holy smokes there's something to this' so although he's like completely obnoxious and annoying at first that there's really something here.

  So I that was my introduction to Llewellyn and I would like to say that as this point I feel like he is becoming a  very good good friend of mine  

Friday, June 3, 2016

Using intellisense for documentation

A few days ago I created an open source project called EclipseTips with help from Aki Salmi

It's a small jar that has classes without implementation that provide useful cheat sheet hints while you are working.

Here's what it looks like

The really interesting thing about this is it is a hack about using editor inline help solely for the purposes of help. This is something I have not seen done before.

Keep in mind that these java classes serve no purpose other than to provide documentation.

Because this is a new area, I wanted to share some lessons learned as well as places I think this could be expanded to.

Lessons Learned from version 1

Hack then Generate

Javadocs is a reasonable place to add documentation when coding, but it is not a good place write real documentation. Once you get the general idea and a few working prototypes, you are going to want to create a way to generate the documentation classes.  

For example, here's how we created the Completions Tips data. We then generated both the mac and windows tip objects from here.

You can take a full look at the generation process here.

Simple Html

While the documentation rendering doesn't support much, you can use simple html like tables and images and UTF8 characters to make your text more readable. Just keep it simple.

Use tl;dr curation

A lot of the value is in the discoverability and quick readability. We approached this in a couple ways.
  • We don't show all the tips, only the ones we judge 'most' useful
  • We grouped things so you could focus on pieces, but we also had a full listing under .Mac()
  • We named the groups starting with an underscore ( _Lines ) so they would be together in the editor

Possible Next Steps

Other Editors

  • Visual Studio / Resharper (for vs keybindings & R# keybindings)
  • IntelliJ

Example / Starter / Cookbooks for Api

When you are getting started you often find your way to websites to lookup quick getting started examples. This as stuff that doesn't exactly belong in the actual code itself. Especially as the examples might be how you discover the packages, class and methods you want to call.

I could easily see documentation classes for things like linq, unit testing, markdown, regex, etc.

Of course, you might want to put that directly on the methods (as documentation was originally intended) but this also opens up the ability to write a documentation project for a project you don't actually own yourself.

Let's see what the future will hold...

I'm excited to see what will come out of this discovery. If you have ideas please reach out to me on twitter ( @LlewellynFalco ) Share what you've created, or ping me and we can pair and create it together.