Tag: Recently Read

bookmark_borderRecently Read

Posted on

“Don’t know what I want, but I know how to get it”
Jeff Patton revisits the basics of Agile development, and one section leapt out at me.

Saying “shippable” to people in the customer role means implies they’d better get the requirements right because that’s the way Agile development works.

Now, I believe Agile people had something else in mind when they said it. I think they mean keep code quality very high. Keep the code supported with unit and acceptance tests. Take steps to validate each and every user story. It tells testers to get involved earlier and more continuously. It tells developers to develop with a higher attention to quality. (Apparently developers would be developing crap otherwise?)

Which is all well and good, but isn’t there something missing? Hello? Product Documentation?? Regardless of his omission (an oversight, I’m sure) If you are involved in a software team using any form of iterative, Agile development then give it a read.

Collison’s Ignorance Spiral
After every release cycle has been complete, we undertake a Retrospective, looking back at what went badly and what went well, with the aim of carrying forward the lessons learned into the next release. I think we are pretty good at it but some of what Chris says is interesting:

I’ve been in a number of lessons learned reviews where the intent of the meeting seems to be catharsis for the team or compliance with the process, rather than learning for the organisation.

Is that such a bad thing? Sometimes the discussion is more important than the outcome, and if the team needs catharsis then surely it’s better to provide an outlet for it? Admittedly I’m taking what Chris wrote and skewing it somewhat, but he makes some good points.

Top 10 Distraction Stoppers
Nice list of useful applications, particularly item 5 “Minimise your Word Processor”. One of the commenters suggested an application called q10 as an alternative to Darkroom for Windows.

I’ve been trying out q10 recently, mainly for the posts on this blog and for an article I’m currently writing, but I’ve slowly been extending it to other things and I have to say it is very effective. It takes a bit of getting used to but if you have problems focussing on your writing, and I mean REALLY focussing, then it might be worth a look.

Project Blogs, Email and Dual Collaboration Channels
Written in response to a separate post, this paragraph leapt out at me:

A larger question is how to efficiently manage processes that, for historic or practical reasons, require collaboration among multiple communities that maintain a mix of potentially incompatible formal and informal communication processes.

It’s something that we repeatedly visit at my place of work, we have a very successful wiki, and we’ve started to ponder if there are other tools out there that might benefit us in other ways.

In my head there is a need for something like Twitter but with the ability to post slightly large amounts of information (not much, say double the character count). That way anyone can post a quick thought for the consumption of others. Very informal but possibly a good way to capture the myriad of ideas that are generated each day?

bookmark_borderRecently Read

Posted on

Christmas looms large, and the days are “fair drawing in” as they say in these parts. I’m taking a couple of weeks off to relax and recharge, and no doubt to eat, drink and be (very) merry. As ever this time of year is pretty hectic, so here are few things that caught my eye over the past couple of weeks.

10 Word to avoid in your writing
A short list but the main point is to avoid gobbledygook. One of my pet peeves is the use of long words when a perfectly valid, shorter, word is available. The Plain English website has some excellent advice if you want to find out more.

No-one reads the help anyway

the next time you hear someone say, “No one reads the help anyway,” say, “Yah, no one uses Google either.”
This will lead to a puzzling follow-up question — What do you mean? I use Google all the time.
Then you say, What do you use Google for? To search for answers, solutions, and information when you have questions?

Like some of the commenters, I disagree with this a little. At a simple level it works, but there are flaws. However, as an opening gambit I think it’s a good one. It will make people stop and think, and once you have them thinking about it THEN you can explain the more subtle differences.

AuthorIT Yahoo Group Search
I’m listing this here so I don’t lose it again. Yahoo Groups are great but the search engine frequently falls over. MANY many thanks to Hamish for providing this resource, this is the kind of thing that makes the Internet great.

Building a successful web community

Do not assume that a community, particularly a successful web community, is easily built from the one ingredient of a shared interest – ensure there is also a goal or a purpose in the mix.

Very true. I know that some Technical Communicators are starting to thinking beyond user documentation, and the next step may well be to nurture online communities around your product. This article has some good tips, and I can vouch for them all having struggled to setup a Scottish Blogging site myself.

Technical Communicators and UI Design
Scott Nesbitt spotted an article about User Interface Design and a particular section caught his eye. It states that the documentation must be considered as part of the design, and Scott goes on to say:

“technical communicators need to get involved not only in the design and usability of an interface, but also how users will access documentation from within the interface.”

I couldn’t agree more with this, and recently I’ve been pushing my team to think along these lines, realising that we work with, and develop, “information” rather than “documents” meaning we need to have a greater sphere of influence.

To coin a phrase, we are the interface to the interface.

bookmark_borderRecently Read

Posted on

Tomorrow we get to spend the afternoon in the pub after gorging ourselves on turkey and stuffing. Yes, it’s the Development Christmas Lunch. This year it’s handily placed right at the end of a release cycle (although that does mean some poor souls may be dragged back into the office), so we can celebrate the release AND the birth of a baby a long, long time ago (or whatever you believe).

That also means that next week I’ll have a little more free time to think about the future, and get some plans in place. I’ve already got a fair list, some of which will feature here.

However, for the time being, here are a few things that caught my eye the past week (or so).

Writing Tips for Non-Writers Who Don’t Want to Work at Writing
As THE core skill of my job, some of this is a little hard to take but sometimes we can be a little too obsessed with grammar, don’t you think?

Grammar matters, but not as much as anal grammar Nazis think it does … Frankly, I think if most non-writers can manage to get agreement between their verb and their subject, I’m willing to spot them the whole “who/whom” conundrum.

Wiki Patterns: The Book
I love it when this happens, a blog I’ve read for ages (devoured some would say) gets published in book format. Needless to say my copy is already ordered.

Human behavior is pattern-based, and wikis are designed to support the
patterns of activity that occur when groups work together. Therefore, there’s no right or wrong way to use a wiki, so it’s impossible to write a recipe for successful wiki use that will work in all cases.

Instead, documenting the behaviors seen on different wikis and classifying those that help the wiki effort as patterns, and those that hinder the wiki as anti-patterns, is a more useful
way to offer guidance to other wiki users.

Use Structured FrameMaker and WebWorks ePublisher?
Sticking with Wikis, here is an excellent article from the WebWorks Wiki: Implementing Help-Specific Features with a FrameMaker EDD.
I probably learned more about using Structured FrameMaker with WebWorks reading that article than I have in the past year of actually using both products in anger (although that’s mainly because the set up here works so I’ve not had to tinker).

This project contains a complete workflow for producing printed and on-line documentation with ePublisher Pro. At the heart of the system is a structured FrameMaker template with an underlying EDD. The minimalist EDD contains a scant nine content elements and yet automatically assigns more than 120 paragraph styles that implement help specific-behaviors in the corresponding ePublisher Pro template.


Building Enterprise 2.0 on Culture 1.0
Sounds a bit odd I know but if you are interested in how to build an collaborative environment in your organisation then you must have a look.

To encourage an organisational shift along the enterprise collaboration maturity model, Enterprise 2.0 leaders should focus on capturing the flow of information. Over time, the flow builds not only a stock of searchable knowledge but also a reputation as the source of fresh ideas and trusted up-to-date content.

And finally, a little house-keeping. I had promised to update the OPML file of TechComms RSS feeds but I’ve not had a free minute. It’s top of the list now though, so expect to see an update early next week.

bookmark_borderRecently Read

Posted on

With the TICAD conference last week, a couple of days in my sick bed, and the imminent product release I’m working towards, I’ve not had a lot of time to post here. However, the RSS feeds keep trickling in, so here are a few items that caught my eye over the past couple of weeks.

What Beautiful HTML Code Looks Like
I’m a terrible coder. Which is just as well because I’m not a developer but as I do dabble in HTML and CSS quite frequently (hey, and PHP too), then this is a good reminder for me to develop my own best practises.

Code is Tabbed into Sections: If each section of code is tabbed in once, the structure of the code is much more understandable. Code that is all left-justified is horrific to read and understand.

Includes a neat infographic, downloadable as PDF, which is now pinned beside my desk.

Procedures: The Sacred Cow Blocking the Road
An update on a (yipes) 10 year old article. I don’t think I read it when it was first published but I have read it. Well worth another visit though.

“It takes a surprisingly short amount of time for a user to feel unstuck. When I was a usability consultant, I used to advise clients to put the critical information in the first three words of a sentence.”

IA Deliverables
From Content Surveys, to wireframes, Personas and Use Cases, a brief overview of each is followed by a sample template. Not only a useful resource but a good overview of the typical process an Information Architect will undertake, a lot of which can be adapted to more traditional product documentation.

Collaboration is not a dirty word
Collaboration on content (not documents, even if that is where the content ends up) was a key part of my presentation. It’s good to see the switch from document-centric to info-centric taking place.

I love things being this easy. I love getting (almost) zero emails with attachments. I love not having a hard drive full of Word documents.

DITA Troubleshooting specialization

The Troubleshooting specialization creates a new topic type that is well-suited for problem-solution information.

7 Ways to keep the post-conference buzz
Not long back from a conference myself, I have already done a few of these things (item 3 in particular) but some good ideas here.

Wikis for Documentation?
Steve Manning isn’t sure about using Wikis for Documentation but does think they could be a big hit in another, related area:

Most writers have to guess about their users. Few writers get the opportunity to speak directly with users. Few get any sort of feedback at all. They are left to do their best. How useful would it be to be able to post your document on a Wiki and have users be able to comment topic-by-topic? To see the questions they ask?

I totally agree. All I need to do is figure out how this works within a single source environment, and tackle a few issues around governance and change management and it could be an excellent working model.

And finally…
I’ll be updating the TechComms RSS feeds download soon, so if you think you should be on the list (or even if you aren’t sure whether you are or not) then let me know. It includes all kinds of stuff which is loosely related to Technical Communications, and I’m always on the lookout for more sources of inspiration. Leave a comment if you think of anything.

bookmark_borderRecently Read

Posted on

Another week (and a bit) has passed. Time is tight for me at the moment, and I’m not posting here as often as I’d like so, for now, here’s a quick roundup of everything that’s zipped past my inbox in the past week:

Resources on presentation design

… advocates an assertion-evidence design, which serves presentations that have the purpose of informing and persuading audiences about technical content

Needless to say, with my first ever conference presentation looming, I’m fairly focussed on both topic relevant stuff and anything that will help make my presentation better.

An XML CMS is simple as 1-2-3

Creating an XML-based Content Management System to single-source technical publications is as simple as 1 – 2 – 3. Rather than focusing on any single tool or solution (and thereby forcing users to change to match the tool), this article describes one possible three-step process for using XML to single source your content deliverables.

A rather simplistic view of things, but if you are a bit flummoxed by the raft of information available in this area, and you aren’t really sure where to start, have a quick look at this. Short, simple and easy as A-B-C.

Make your writing east to scan

… the acid test is looking at your information as your reader/user would see it, and asking yourself “can I find what’s important without reading the whole page”?

You can format your text in a variety of ways, but it pays to take a step back and view the format of your content from the point of view of your readers.

Getting to the web-first mentality
Interesting to read that other professions are struggling to embrace the internet. Ultimately I think it’s getting to the point where we just need to take the plunge.

Start putting the web content management system into the workflow at the front end. This could be as simple as using Google Docs as a word processor instead of the bloatware that we know as MS Word.

Collaborate or fail
Titled “Building a Collaborative Team Environment” the opening couple of paragraphs kept me reading:

Technical communicators work hard to meet deadlines and value the standards inherent in the profession. At the same time, they value their personal creativity and the responsibility for developing a complete publication on their own. They tend to enjoy doing everything from writing, editing and page layout, tographics, technical content, and more.

Working as part of a team to create a single set of deliverables, handing over responsibilities to fellow team members, and trusting the work produced by others does not come naturally.

It’s an excellent article, looking at a variety of ways in which we, as technical communicators, can adapt how we work. It will no doubt prompt some posts here as I digest it further.

And on that, somewhat culinary note, I’ll thank you once again for stopping by.

bookmark_borderRecently Read

Posted on

12 Lessons for Those Afraid of CSS and Standards

“It took me two years to break out of the comfortable prison of layout tables, and another two years before I could use CSS to produce layouts that were originally intended for tables.”

“The buzz about Web 2.0, CSS, and myriad other subjects of the bleeding edge can become a dull roar to those left ill-equipped for industry changes because of work habits adopted in good faith years before. It is my hope that the experience I’ve shared will help some folks to find a way back to the top of the heap—which is where the web needs you.”

But don’t be afraid, Ben Henick offers some lessons that will help get you through. It’s based on real-life experience and mirrors my position. CSS and standards are good, yes they can be strict taskmasters but remember that 100% compliance isn’t always required, sometimes 98% is enough. As Ben points out in Lesson No. 9: “In the real world, stylesheet hacks will get your project across the finish line”

Design Engineering

“The common expression “Engineers build bridges” is actually a misnomer. Engineers build mathematical models of bridges and draw little pictures of bridges on paper or inside computers. Ironworkers are the people who really build bridges. This inexact, industrial age metonym has led to much confusion in the post-industrial age, where it’s all too easy to confuse software designers with software welders because they both use the same tools and raw materials for their very different work.”

Not sure I agree with all of this but I always tend to learn more from a differing opinion.

What do you seek — Documents or Knowledge?

“Document management can only point you towards documents, like a traditional search engine. In contrast, when you’ve got information on a wiki you can search for information, link to it, reference it, update it, secure it, blog about it and share it.”

I’ve been pondering the possible questions that might crop up when I give my presentation on using Wikis in the workplace, and this is a great answer. So much of using a Wiki is about breaking the document-centric working practises that slow us all down. Don’t they?

The Spiral of Wiki Adoption

“Although reliance on email and familiarity of other tools may illustrate a reluctance to ‘unlearn’ habitual less effective work practices, there needs to be a balance between directive wiki usage and support for different communication styles as people become accustomed to using wikis and the different capabilities they can provide.”

During other research I found that just getting people to start using a Wiki was the hardest part. Once they started, they soon started using it in ways not previously considered. In other words, Just Do It.

And finally, two quick links. One I’ve known about for a while but recently cropped again on TechWR, and the other is just for kicks. Although I do often wonder if people do Laugh Out Loud as often as all that.

A List Apart: Style Guide

LOL?

As ever, I’d love to hear your thoughts on any of these. Particularly the Design Engineering article which I must admit I partly agree with but I do dislike the “them and us” tone.