Developer Usability

dials.jpgReflecting on my activities in the last few months (especially around Sling and how we use it), I notice that Developer Usability is often my concern.

How do we make our software more understandable, transparent, efficient and generally usable by developers? Good designs should be self-explaining, but in a complex system that’s easier said than done.

There are many small things that influence this, as well as architectural decisions where one might trade off other criteria for developer usability.

I find it captivating to try and improve things so that people understand them better – I’ll try to find out more about what makes the difference here, but for now I’ve made a few suggestions related to documenting Sling, which would hopefully apply to other projects as well.

(Update: see the next post for a more general view on those suggestions).

I’m starting to think that documentation is like code comments: if you need lots of it, that’s a bad sign.

Feedback is welcome.

Picture by agathabrown, under morguefile license.

7 Responses to Developer Usability

  1. Niall says:

    I agree with the issues you identify, but good docs take effort and I don’t think theres any avoiding that. Seems that your strategy starts with the premise that wrt to docs you’re going to fail – i.e. no-one is going to put in the required effort on an on-going basis – so lets avoid failure by lowering the goals from the start (i.e. don’t try to provide good docs) – but provide something else with which hopefully the users will get by with. Perhaps this is a realistic approach – but I’m sure you’ll hear complaints from users about it.

  2. bdelacretaz says:

    Thanks for your comment Niall!

    You’re right that I assume we don’t have enough resources to create ideal docs, but I don’t think what I envision would have less value for developers. In the end it would just be a different way of organizing the info, less static and more oriented towards hypertext than paper.

    The unit tests in the Lucene book, for example, have the same value as standalone examples for the reader, but they are much more trustable.

    I hope to be able to report success w.r.t. Sling – but only time will tell.

  3. Christian Sprecher says:

    Hi Betrand

    I already had a take at sling. As an outsider I can say that the best approach to understand a software is to have a real task on hand: “I want to reach that goal, what the heck do I have to do?” Perhaps it makes sense to have the documentation organised in different trails. All those “Create blog in 20 mins”-Vids are good examples for task-driven approaches. I dont have any clue wether this approach does scale with complexity of a software system, although chances are good that for a well designed system a certain modularisation within the documentation is possible. One (imho) good example is the documentation of the Spring framework.

    I personally do not think that lot of documentation is bad, but rather the fact to have to read alot to get started with something…

  4. bdelacretaz says:

    Thanks Christian for your comment – point taken about the “create your blog in 20 minutes”, that might a good starting point for a Sling example.

  5. Rene Robinson says:

    I disagree with the premise that more documentation is bad. I will agree that well written cod goes a long way to making things understandable, but that only helps if you know what you are looking at. What about being introduced to, oh say sling. What is is? why do I want to read about it? how do I get started? etc.

    I had the same questions when I started with CQ. I also berated ( nicely ) the Day folks about the lack of current docs, a clean layout, understandability and lack of a clear starting point. There seems to be an assumption that good programmers/engineers make good documentation people. It takes a really good documentation specialist to tease the information from the developer and reduce it’s complexity to something that can be explained in simple terms.

    Simple is HARD. Think about writing simple code to handle something. It’s very hard. Look at Unix, simple in it’s implementation and design and yet, functions beautifully.

    Don’t discount documentation; it can make or break your software.

    Rene’

  6. bdelacretaz says:

    @René, even though I’ve been a bit extreme in my post, I don’t think our views are so far apart, and totally agree that documentation specialists are needed to create useful docs.

    What scares me about the docs though, is when they have to repeat things that are already defined elsewhere, like in the code: writing the code (or the tests, see my other post at [1] about that) in a way that is readable enough to (automatically) include verbatim excerpts in the docs, can help a lot in making sure the docs stay in sync with the code.

    [1] https://grep.codeconsult.ch/2008/03/13/automated-tests-are-the-best-reference-documentation/

  7. Rene Robinson says:

    Hmm, Yes we may in fact be saying the same thing. My point about simple is that if I want to write an example of code, I find that I have to refactor the code a lot to get it to read “English” like. Something like:

    If ( no_more(tokens_from(input_string)) {
    blah, blah
    }

    (hmm, even that sample snippet caused me to re-factor 3 times…). My end goal when I used to code as to make it easy to understand, because I always ended up looking at the code years later. I wanted the intent to be obvious because I too didn’t like to maintain my comments in sync with my code. I come from a assembler/f66 background and with assembler you must write comments.

    The best example I ever crafted was a class project for Fortran class. I knew Fortran cold, so I wrote a pretty printer with cross-reference and ran the program thru itself, and submitted the output for my final grade. It was truly human readable even with 6 character subroutine names.

    As far as repeating things, that seems to point out a need to reorganize the material.

%d bloggers like this: