Jens Alfke’s latest blog post rambles about a couple of things but finishes on something that I really empathised with:
Apple engineer: …and the layout needs to take into account ligatures and contextual forms, where adjacent letters change glyphs depending on neighboring characters, or even merge into a single glyph.
Sun engineer: C’mon, is this important? How many people need advanced typographic features like that, anyway?
Apple engineer: [after a pause] Well, there are over 900 million of them in India alone, and another 200 million or so in the Arabic world.
Sometimes it feels like I’ve been bashing my head off a brick wall for, well, years. Motivating people to not do ‘half-a-job’ is actually hard.
Yesterday I almost had a stand up argument with a guy in my team in $BIG_COMPANY on the definition of ‘complete documentation’. I want documentation that can be read and understood by novices and managers. He wants it to be opaque enough so that you require understanding in order to work with it. In the end we sat down and he demonstrated it to me and I tried it. Within about 5 minutes we hit the first stumbling block in his documentation. He asked if I had the database interfaces set up. I replied “The what, the who and the where?”. So we need to add a piece about database interfaces. Then we needed to add another piece about how to log into the server. Then how to run an update. Then how to publish the updates. Then how to check the updates have been completed. In all, the additional bits were more than twice the original document and spawned two more wiki pages. In the end he agreed with me, the documentation was half done but the journey was a lot harder than it should have been.
Writing technical documentation is not an art. Writing it for non-technical users in order to help them learn is not an art. It just requires removing assumptions.
When building my second office in Mac-Sys, we had a square room to modify and the original assumption was to put a single wall, parallel to one of the other walls, in. By questioning the assumptions (that a single wall, parallel to another wall was the only way to go) we put in a ‘shaped’ wall which provided us with nearly 50% more wall space in a room where wall space was a premium (for shelving, storage, desks, etc).
If you’re in a job you don’t like and your choices are (or seem to be)
a. leave
b. suffer
Then you really should be looking for c.. I can’t tell you what c. is for you but when I was in Nortel it was as a simple as bringing in a laptop to work with me and increasing my productivity (and reducing my frustration with Windows NT). There may be ways you can change your work day in order to improve your work life. Would working part time from home make a difference? Would time-shifting your work day by an hour help? (I much prefer working from 07:30-16:00 as it removes a LOT of traffic from my commute).
Remove your assumptions and consider new ways.
There is always a c.