A suggestion for those who create projects for open source

Please include a tutorial on how to use your product.

An example of this:

I saw a talk on FiloDB. It sounds like an interesting time series collection database. The technical challenges sound interesting and the architecture sounds like its sensible. However, when going to the project, there’s nothing there that will get me off the ground and working with it quickly.

TL;DR Write documentation in a manner which it helps to lead the user to use your product/project successfully.

Spring Security OAuth- The missing Instructions

The problem and lead up to the solution

I have been working on an authentication issue for more than a month. This has been incredibly irritating, and I have not found anything related to this online – not even in Stack Overflow questions. The issue is that I followed the instructions for installing Spring Security, Spring Security OAuth, and the Google [etc] plugins for my existing application. After following the instructions to a T, I clicked on the authentication button for the Google OAuth. What happened? I was sent right back to the login screen.

 

This was rather weird. My first few thoughts were:

  1. Did the authentication fail?
    After an investigation, found this to be false. Chrome’s developer tools showed that the network path redirected to the /oauth/callback and then to /oauth/google/success. So that was a no.
  2. Was the redirection page not working?
    I really had no idea on this. It seemed to work for the locked-down resources. But I still seemed to have received the login page after coming back from Google OAuth. That’s logged within the Spring Security plugin depths.
  3. Was the authentication return point getting rejected?
    Here we would have a loop back to the authentication page.
  4. What controllers were getting hit?
    The debugger won’t go into the controller call itself. Also, the expected controller wasn’t getting hit. So this wasn’t of any help.
  5. Were the Plugins incompatible with my Grails 2.4.3 application?
    I was using the most up to date plugins for Spring Security. (The most recent publication date of May 2014 didn’t help with this concern)

 

After these thoughts, I was stuck. There were other scenarios on Stack Overflow and mailing lists that made claims to the plugin not working. However, most of those issues were resolved by switching plugins or due to syntax errors in the config. Additionally, I checked the plugins’ issue pages and there was apparently nothing about the issue I was having.

 

To answer the third idea of where the problem could be, I looked over the following static set of rules configured in the config:

 

grails.plugin.springsecurity.controllerAnnotations.staticRules = [

‘/’           : [‘permitAll’],

‘/index’      : [‘permitAll’],

‘/index.gsp’ : [‘permitAll’],

‘/assets/**’ : [‘permitAll’],

‘/**/js/**’   : [‘permitAll’],

‘/login/auth’ : [‘permitAll’],

‘/**/css/**’ : [‘permitAll’],

‘/**/images/**’  : [‘permitAll’],

‘/**/favicon.ico’: [‘permitAll’],

‘/oauth/**’   : [‘permitAll’]

]

 

After all the addition of the login/oauth bits were recommended in the documentation.

I even tried testing Google’s side with the console. Everything worked on their end. My assumption was that if one of the plugins was misconfigured it would try to alert me via the logs. (Well, as I learned that assumption made an ass of me.) Finally I did some research within the plugin. I found the package structure in which I could bring in the logs.

 

trace ‘grails.plugin.springsecurity’

That eventually lead me to a lot of logging about only the filters/interception of web traffic, which didn’t help very much, and it still lead me to question what was going on. So I tried logging the service and controller methods. (That lead me to realize that I was never getting the actual OAuth plugin to kick back in on the way back. Additionally I found this bit in the logs (that were enabled earlier):

 

intercept.AnnotationFilterInvocationDefinition no config for ‘/springsecurityoauth/onsuccess’  (which was followed by a redirect to /login/auth.)

 

Google was not much of a help for this method. Nor was it a lot of help for the ‘springsecurityoauth/onsuccess’ path. This meant that the access to the actual controller SpringSecurityOAuth::onsuccess method couldn’t be reached. This was a bit confusing since the Spring Seucrity OAuth defines it’s own URL mappings in: SpringSecurityOauthUrlMappings. Alas, it’s a static call. I’m not able to debug that low.

 

This led to another path: Well how are the other path’s defined, and why isn’t /springSecurityOAuth/onSuccess allowed. SpringSecurityOauthUrlMappings maps the controller to /oauth/$provider/success, and that’s allowed under my rules.

 

The Solution

Well that path isn’t allowed. Why? Spring Security has 2 ways to lock down your application.

  1. InterceptUrlMap Method: Statically define all of your paths/roles via a static map in the config.
  2. Controller Annotations Method: This allows for you to define some static rules requests are allowed and to what accounts in the config file. It also allows for you annotate your controllers/methods to what is allowed by what role(s).

 

Guess which way I went. Yep, I went the progressive route and chose the controller annotations method. That worked really well for what I had, and with authentication outside of this plugin. But it failed when trying to return. Why did this still fail? Well the configuration of springsecurity.controlelerAnnotation.staticRules = [ …. ] was missing the reference to the controller (that looks like a url): ‘/springSecurityOAuth/**’: [‘permitAll’]

After adding that small change: everything worked. A lot of time was lost. I’m going to need a break away from Spring Security. That and probably quite a few drinks.

What could have been improved?

The documentation needs to be updated to mention controller annotations.

Are all technical books dry and boring?

After reading many technical books I believe that a trend has emerged: Most technical books tend to be varying degrees of being dry. This is starting to become incredibly irritating, it also hurts in keeping the readers attention. At the moment I don’t have a lot of justification to support why non-dry techincal book, however some of the most memorial books  have included silly examples, real world examples, and a non-referential tone.

 

So far the only books I’ve read that didn’t have a dry tone:

1. Test Driven Development By Kent Beck

2. Effective Java- Joshua Bloch

3. Head First For Design Patterns

4. Apache Wicket in Action – Martijn Dashorst

A Few Signs That Your Project May Be In Some Serious Trouble

  1. Lack of leadership in developer operations
  2. A lack of reporting of improvements in code reuse, coverage, test cases, and stability.
  3. Underutilization of frameworks and libraries used within the project.
  4. Lack of disposable runtime environments [for development and testing].
  5. Build times are unknown.
  6. Long and detailed documentation is required to build your product.
  7. Dead code is left in the code base to rot for years.
  8. Bugs are being reproduced as unit tests.
  9. Third Party dependencies are not being upgraded.
  10. Code is badly organized. Models are placed anywhere, packages aren’t organized, etc.

Getting Over Writer’s Block

A while ago, Tim Ferris was asked how he was able to accomplish the task of writing books of considerable length. The advice that he was given was: Write 2-3 sentences every day. I cannot recall who was the interviewer or the advisor. Note to the reader: It is possible to find this video on the internet, but I have no idea where it is. More help: It was after the {{4 Hour Chef}} was released. This is great advice and has helped me. I have difficulty writing at times. When I’m faced with a large writing task I tend to become unmotivated. Writing two sentences is an easily accomplished task, reduces stress, and creates very manageable goals. This becomes incredibly helpful for when you are passionate about the subject, but your motivation for writing is lacking or your worry of getting your message across effectively is important. If you are extremely passionate about the subject I believe that you’ll find that after writing those two sentences your writing will transform into pages of text.

If only I knew this trick in college.

Additionally I don’t find that this trick works 100% of the time, but the writing becomes much easier when you create a framework for what is to be written beforehand. This is also true with writing code.

Don’t trust your Technical Documentation Staff to write Quickstart guides and Tutorials, Hire a Professional.

This is written with an audience of producers of software products/services in mind. Please do not claim that your documentation, used to introduce a new user/developer, is good enough to make the user/consumer (developer) proficient in your technology. Producers of software products [the developers, and organizations] are great at writing references to their products, however they generally are horrible at introducing new users to their product. When quick start guides, or introduction tutorials are written for products, the documentation tends to remain in the domain that the creators made. Solution: Hire a reputable technology writer. This will help you in a few ways:

  1. Gets a credible authority figure giving approval and backing to your technology
  2. Loses a creator bias
  3. The writer, like your audience, has an outside knowledge of other technologies
  4. They should not be influenced by the creators to write things that lack value to your actual users. (This assumes that sales and management cannot affect the contracted author’s work.)
  5. The users will understand the product better, and thus reduce undesirable support calls/emails.
  6. You will have professional documentation. The technical writer’s domain is to create attractive and easily consumable books, the software producer’s domain is not the same.
  7. From a business sense, the author is not a full time employee; they would remain as a short-term contract. Insulation from actual production is a good thing. This also helps the author as that it stabilizes their income streams.
  8. The documentation is written from a potential customer’s perspective
  9. It gives quick feedback on how easy the system, language, or product is to use, setup, troubleshoot, and possibly maintain.

Given these points, it would be easy to justify even a luxurious price on producing high quality introductions / non-referential documentation for your products. Based on these reasons, I conclude it would benefit the business professionals, developers, testers of the product, users, and the marketing department by separating the author him/herself from the general stress of the entire producing company.

Technical Writing for Programmers

Forewarning: I’m not an expert on this subject, however I do play one on television.

Software engineering is mostly a solitary, and technical occupation. Most of the non-programming language communication made by a developer is communicated to another person with domain, contextual, and similar technical knowledge. Very rarely, information is communicated to someone outside of the domain, or contextual atmosphere, let alone technical knowledge. This guide is more of a collection tips and reasons to document that I’ve discovered over the years.

  1. Acknowledge your audience. For frameworks, nothing is more frustrating to the reader when a quickstart guide is written for existing developers of that framework. Those developers do not want a quickstart guide, they want the Java/Net-doc. I’m looking at you Spring. If your audience is technical and new to your framework, please identify concepts that are exercised within the framework. Preferably, as an appendix and referenced to at the introduction of the book/document.
  2. Proof-read the document, even better: Have someone, even better people, from the targeted audience proof read the document for accuracy and readability. It is unbelievably surprising to discover how difficult it is to write documents that deal with troubleshooting, installation, configuration, or documentation of “common tasks.” From my experience, just the modification of an existing code base to add a new report took 4-5 pages of bullet point instructions. Once a documentation guide is published errors/incorrect documentation is embarrassing, are difficult to correct, and can be very costly.
  3. Screenshots: Screenshots make describing tasks involving a GUI clearer.
  4. Pictures [more than screenshots]: Reading words are useful, however a simple diagram is often useful for explaining complex architectures, or tasks. It also includes people who are visual learners.
  5. Versioning the document: This helps the user identify the document’s “up-to-date-ness.” I really hate advising this, as that some documents begin to include the change list. [Who really cares about this? All I want to know, as a reader, is if I have the most current version]
  6. If you are documenting source code and haven’t written by the time that you get to the unit test. Write the documentation while the tests are being written. If the documentation has already been written, write the unit tests based on that, even if you have access to the source code. From my experience this can piss off the original developer. However, as a tester, you should depend on the resources given to you, not what the actual structure is. From my experience, this level of pedantry can piss off the original developer, but in the long run it may prevent major errors in future reuse of the code. Make the unit test break if the documentation isn’t followed!!
  7. Provide documentation! Your developers/designers/user’s are very intelligent, however being intelligent does not make one a mind reader. Don’t expect another person to understand your [or your team’s] motivation, history, design decisions, or politics surrounding the project.
  8. Allow for feedback. If there is mistake in the documentation, provide the user to contact the author of the documentation for confirmation of a mistake. If you don’t do this, expect for people to be pissed off about your API, idea, project, source code, or product.
  9. Document bugs or deprecation: If something doesn’t work or is going to be removed. Warn the developer.  It’s better to know beforehand.
  10. Support: Support is more than a scripted technical support call. If you have better documentation low level support calls can be eliminated or substantially lessened. Additionally, supporting the documentation/product can give insight to the functionality used in the product and/or bugs that were previously not found.
  11. Job Security: It may sound contradicting (Most people I’ve talked to claim that obfuscation keeps a person employed for a while, at the expense of others), however it’s hard to claim that a person isn’t doing the job they were tasked with, or deny a promotion if their procedures are sufficiently documented.
  12. Documentation can help you identify architectural and interaction [GUI, and API] issues. This is more of a case of an problem, previously unrealized, coming into the consciousness. You’ve identified the issue, now you can talk about it and come up with a solution.
  13. For APIs: Provide examples for every method. Write a paragraph on: why someone should use that method, why one shouldn’t use it, the performance and memory costs, and the state change to the operation of the software or environment.

Have tips for technical writing, documentation? Leave them in the comments! [See I even provided feedback for this post :P]