I’ve worked in many types of organizations though mostly in public and non-profit, and it seems particularly in smaller organizations, or in organizations where they’re not building products, documentation is not always seen as necessary. I once asked a manager to attend the Write the Docs conference and they didn’t think it was relevant to my job. Granted, writing documentation was not part of my job description, but I didn’t quite understand how they couldn’t see its importance. Documentation is not just about product documentation. Continue reading “Documentation is important in every organization: Writing down all the things”
by Nicola Yap in collaboration with Sangeetha Alagappan and Darcy Lima Continue reading “Notes from Write the Docs Toronto: Creating accessible docs”
I totally blame @yo_bj for this talk since she was the one who pushed the lightning talk sign up board at me. I hope it was interesting and/or useful to some people. Continue reading “Write the Docs Lightning Talk: Write the Accessible Docs”
I started drafting something similar to this post for our website and decided to make it a blog post first. People ask me all the time about accessible formats (aka alternate formats) and the differences between the various types. Continue reading “A Rundown on Accessible (Alternate) Formats”
Okay, so I know we have the CSS3 multiple column layout “columns” property in the newest browsers, but working in public institutions where we are expected to support IE as far back as version 8 or sometimes 7 (in the very rare case even 6 still), we cannot rely on the columns property… yet. Continue reading “User Readable CSS: Columns”
So I started at CILS 3 weeks ago, and oh boy does it feel longer. My first week was a lot of getting settled in sort of thing (which means orientation and a lot of paperwork), and being given the simplest of stuff. After the first week, I was thrown into the deep end. Continue reading “Getting Thrown into the Deep End”
Hands off! Best Practices and Top Ten Lists for Code Handoffs
- Naomi Dushay, Stanford University Library
Code handoffs are never smooth. Ever.
Ratio of time spend reading vs. writing code, 10:1.
The Truck Test
- what if you were run over a truck and someone else had to take over?
- need to code so a stranger can read it and understand it
The Boy Scout Rule
- “Leave the code cleaner than you found it”
- need to maintain your code
- otherwise you’re part of the problem
It’s More Than Code
- naming should make sense: servers, scripts, everything
- config files should not point to boxes
- tools chosen can be the problem
- should you be rolling this on your own?
- probably something been done before
- some think if you write code really well, then you don’t need to comment. Not true.
- Documentation and comments are there to inform, explain, clarify, warn, need maintenance
- readme’s should make sense
- tests are code, should also think about readability of these
- failures should be addressed ASAP
- KISS – Keep It Simple Stupid
- DRY – don’t repeat yourself
- follow conventions
- meaningful names: variable, method, class, file
- small, single purpose methods
Cleverness that reduces readability isn’t clever.
- Clean Code: A Handbook of Agile Software Craftsmanship by Robert Martin
- Refactoring: Improving the Design of Existing Code by Martin Folwer et al.
The Care and Feeding of a Crowd
- Shawn Averkamp, University of Iowa
- Matthew Butler, University of Iowa
- transcribe items in collection
- omeka + scripto + mediawiki
- still in development: want to add social media aspects/integration
- err sorry, brain temporarily sort of died. See slides and I’ll go get a cookie to recharge
How to be an effective evangelist for your open source project Creating a Commons
- Bess Sadler, Stanford University Library
Lost a member of our community this year: Aaron Swartz
- helped to define Creative Commons licenses
- 3 versions: machine, human, and lawyer readable
- code4lib should do the same principle
- shared engineering practices are becoming more and more important
- investment that’s worth it
- please get code contributors to sign a contributor license agreement
- can determine whether contract allows participation
- don’t want to lose informal sharing, but law cases have happened and we need to protect ourselves
- what are we building?
- we are building a culture, a commons
- Fedora4lib – came early and rented a house together
- Hydra = a community
- cultivate a place where we can
- teaching at Ruby on Rails workshops – too big a job to leave to a small group of people
- how is knowledge acquired?
- how do we decide what’s true?
- collaboration with disregard of conventional mental thinking
Building the Community
- need to expand and include everyone who wants to join
- more steps in building a more inclusive community
- adopted a code of conduct, because it was a good idea and making an explicit statement
- need to let other people to know that we’re trying
- “We are all imposters.” – just acknowledge it, we all feel that way, but bolster ourselves
- allow ourselves to be seen even when there’s no guarantee of success
- we can support each other
- cannot be accomplished alone
- want to craft a process for submitting issues
Thank you, code4lib!
And that’s it! Until 2014.
So inspired by the ASIS&T Cool Tool Day, I thought it’d be neat to do one of these since there weren’t many volunteers to do lightning talks/presentations at the code4lib Toronto meetup this time around. Our attendance was a little… paltry, but we had some great presentations! Here are my notes from the session.
Presented by @waharnum
- working with REST based web services
- testing automation tool for web services
- best for building with other API
- autogenerate stubs using WSDL
- interface between internal systems
- good for documenting web services, code style with examples
- normally, mostly used for unit testing
- virtual card based whiteboard
- flexible for planning based
- great usability/UI
- even has mobile apps
- maintaining HTML email templates
- also works as a crazy text editor for nerds
XSL Transforms plugin in Firefox
- local reporting
- anything XSLT with just a few security restrictions
- e.g. SVN reporting
Presented by @adr
- cross platform presentation
- push from laptop to another computer
Sidenote: Other Presentation Tools
Presented by @ruebot
- pathogen – linking for VIM plugins to automatically load VIM plugins
- nerdtree – pull files quickly by displaying directory/tree
Presented by Pomax
Thimble HTML/CSS Live Web editor
- teach anyone (kids, adults) HTML and CSS
- use existing projects to make it fun!
- easy inline flickr search of CC images
- attribution in alt text
Presented by me
- monitor hue changer, supposedly to help people sleep better by telling your body what time of day it is
That’s it! Hope to do another one of these or lightning talks next time.
Hopefully this post does not sound like just a rant as I admit that this post has come up from my frustrations from using other people’s work, but I think this is particularly symptomatic of areas where there are not always IT experts, as is the case with many libraries. I also do not boast that I always know what I’m doing, but that’s why I think it’s invaluable to have some kind of code review process.
Making it Simple
As a general rule, better to make things as simple as possible rather than using complex methods if they both achieve the same things. I’ve been told that simple and clean code is the best kind of code.
There may be efficiency concerns involved, but then that seems to be left behind in the cases I’m talking about anyway. (Case in point, our website had 5+ CSS files, not all which had clear purposes, many of which were overwriting each other’s classes, which I had to rework into two files.)
Document and Comment
While some of the simple things might be obvious and self-explanatory, I don’t think I’ve ever seen anything over documented/commented in the ‘real world’ (as opposed to school work), so more is (generally) better. I think it’s doubly important where the creation of a product/tool might be outsourced, but the maintenance of it is done in house (as frequently seems to happen), that the code can be understood by a new/beginner programmer-type person.
Too often I have looked at code recently and thought “what does this do?” or “how many pages does it affect?” While I admit that it’s not always easy to know what or how much needs to be documented, because you don’t always know who will look at it in the future and things you write yourself tend to make sense, but do at least a minimal amount of documentation and commenting.
On a side note, do not name files or functions after yourself (one former student’s name is now unforgettable for that reason and this was created months before I started).
Ideally, there is someone who is an actual programmer on your team or in your unit who you can ask to take at least a quick look over what you’ve done and give you feedback on whether you’ve done it correctly. If there’s no one ‘inside’, consider asking someone on the ‘outside’.
Within a team or unit, if there is more than one programmer-savvy person, consider establishing a Review/Feedback step in the process as you typically see before code commits (if this doesn’t already exist of course).
If you really can’t get feedback from someone else, then much like editing your own writing, step back from it (for, preferably, a couple of days) and look at it with fresh eyes and ask yourself some of the important questions, but namely:
would someone else be able to step in and easily understand what your code does?
I believe that all the above points apply when working with students too. It’s okay if you’re not a programmer. At least take a brief look at the code, see if commenting is done, ask about the general process/framework, ask if they think a beginner programmer would be able to understand their code easily, etc. If you ask, it will at least make him/her think about it!
The end product does not mean it is what you want. Other people also need to be able to maintain and customize/modify. This all seems so obvious, but I think it bears reminding sometimes.
Documentation, tutorials, and user guides must evolve and be updated as technology and software move ahead, but when so many web-based applications use the same basic WYSIWYG, are basic tutorials even needed anymore?
This issue was brought up recently with our wiki’s update to the newest version of MediaWiki. If you use wikipedia at all, you’ve probably been using the new version for quite some time now. One of the greatest improvements for the end-user is the new toolbar.
It covers all your basic formatting needs including tables (which is not the easiest for new users to figure out). The help section is really nice too (since MediaWiki is not a WYSIWYG) showing the user how something will display (of course there’s always the preview button).
After this update, I realized that users will unlikely need as much guidance in editing their wiki pages and the basic tutorials that I created don’t really seem to be needed anymore, or do they? I haven’t exactly polled my users on this issue or anything. For the moment, I have kept it live and updated as it’s being used as a general help article as well. Maybe some users need a bit more structure via a linear method of creating pages, but it would be interesting to know…