Some assignments are very difficult. I am confronted with a complicated GUI or device and have a really hard time explaining to the user how to operate it. I meet with the client again to get additional information and explanations but in the end I’m not happy with the result and the client usually isn’t either. I used to always blame myself for not knowing how to do my job properly, but lately I’ve realized it’s not me it’s the device.

I have written hundreds of manuals and don’t take on projects that I can’t grasp from a technical point of view. So we can assume that I am a competent technical writer This may sound kind of conceited, but I’ve come to the conclusion that if I have trouble writing user documentation for a product it is because it is poorly designed.

In copywritng this can also be a problem. Clients may be unsure about  why a customer should buy their product and not the competition’s. If they can’t provide a clear answer you might end up with something like this:

Insane trip. Our ride from DC to New York took 8 hours – the police along with homeland security vehicles blocked off two stretches near air force bases on I-95. We arrived way behind schedule and had to set up in 10 minutes. We didn’t even have time for refresh ourselves and say hi to our friends. We then jumped right into playing our duo noise set fully utilizing the sound, equipment, and the space of a rock venue. I thought my bike sounded great through the PA system. Jack Tung said that our set was ‘brutal.’

Thanks to Kite Operations for inviting us play and again, congratulations to your new album Festival. It’s breathtaking. It’s a feat!

We didn’t even have to set up our recording devices. Thanks to Dave Yang of K.O. and many other for documenting our set!

pictures by Tom Lin

**Bikes bikes bikes!**

“Irigaray”

“N+1 to the Floor”

I get this question a lot from users, so here is the rundown on our products and what is happening here:

PolarCOM is not the entire product, rather it is a GPS instrumentation and NMEA communication application. To get chart/live GPS/ship view you need both PolarCOM and PolarView, as well as “Core Navigation License” – all together they comprise real time navigation application (known as PolarIS).

PolarCOM is a “kind of” a service. As such, when you run it – it starts in system tray (on Windows)  where you should see a small “blue globe” icon. On Mac it will be activated in launcher. You can reach PolarCOM options by right-clicking (or cmd-clicking) on the icon in system tray or launcher respectively. The suggested use is to launch PolarCOM once and just keep it there, in tray, for as long as computer is up. The chart/ship viewer can be started and shut down as convenient, to save power, increase battery life and free up CPU and screen for other things.

If user exits chart viewer, PolarCOM will keep currently navigated route and all the related information. When user launches PolarView again, this information will be restored and the navigated route will become visible again.

For CRM 4.0 and Excel 2007.

http://crm4documentation.codeplex.com/

For CRM 3.0 and Excel 2007.

http://crmdocumentation.codeplex.com/

Available on the wiki you will find documentation on how to start using the latest 1.6 beta to develop for iPhone, Android, and Palm with the same HTML, CSS, and JavaScript code.  I hope this helps you creating the apps that you want.

I’m still working on getting Blackberry development to work the same way as the others but I’m close to having something that works.

I’m also uploading 1.6 beta6.  It makes some small fixes related to the Images directory in the project.  If you are using beta5 you should upgrade.

 1ère étape : Définir les besoins des utilisateurs

  2ème étape : Collecter l’information

  3ème étape : Traiter l’information, l’analyser, l’organiser

  4ème étape : Diffuser l’information aux différents utilisateurs concernés

Pour faire de la veille on peut utiliser principalement Internet. ( Il s’agira essentiellement de la documentation electronique)

Sur Internet, on peut s’abonner à une fonction de google, appellée GOOGLE READER.

Il suffit de créer un compte, puis d’aller sur un site qui nous intéresse, et sur lequel on souhaite être au courant des dernières nouveautés … puis de cliquer sur l’icone “flux RSS”.

Flux RSS :

L’URL de ce site se rajoutera dans votre compte Google reader, et lorsque des nouveautés apparaîtrons, eh bien vous en serez informés par mails, sur cette fonction de Google.

L’association Via Sèva et l’ADEME viennent de publier le guide de l’usager du chauffage urbain.

Ce document  pédagogique d’une vingtaine de pages se compose de 5 parties :
- généralités sur le chauffage urbain
- organisation et gestion
- tarification et facturation
- qualité de service
- énergie et environnement

Ce guide peut être consulté sur le site de Via Sèva. Il sera également distribué par l’ADEME, via les Espaces Info Energie.

> Guide de l’usager du chauffage urbain

In my last post (read it here) I showed the results of a new documentation process for CruiseControl.NET. The aim was to move the documentation from being split over two different locations (code and the wiki) into one (the code) and to make it easier for developers to write documentation (plus it also standardises the documentation!)

To do this I have used doc comments in the code (yes it bloats the code, but with Visual Studio these comments can be collapsed). Most of the time I tried to use the standard documentation tags (e.g. summary, remarks, example, etc.), but unfortunately the standard tags don’t cover all we need

The good news is when Microsoft wrote the doc comment extraction application they didn’t enforce the tag types. This means we can add additional tags and they will happily be extracted. Of course, we don’t want to go overboard as the intellisense in Visual Studio doesn’t know about them (does anyone know of how to add new doc comment tags to Visual Studio?)

The new tags I have added for classes are:

The new tags I have added for fields and properties are:

Additionally I expanded the code tag (this already exists) to have a title attribute. This will apply the title to the code example block – Confluence allows code titles, so it nicely ties the two together.

The documentation generator mainly uses reflection for the documentation. However this generates the bare bones of each article. For example, this is what the state element looks like:

This is because this class has no doc comments (none at all!) associated with either the class or the fields/properties that are reflected.

Adding the summary tag adds the description:

Adding a title tag:

And a version tag (this was a guess):

Finally, to add an example I used the example tag (with the new title attribute):

Finally the configuration element data is added by adding the default and version tags to the actual property definition:

Notice how this was a progressive enhancement of the documentation. If we added a remarks tag to the class documentation we would get a notes section (this element doesn’t have any notes at the moment).

The doc comments for the class look like this:

/// <summary>
/// The File State Manager is a State Manager that saves the state for one project to a file. The
/// filename should be stored in either the working directory for the project or in the explicitly
/// specified directory. The filename will match the project name, but will have the extension .state.
/// </summary>
/// <title>File State Manager</title>
/// <version>1.0</version>
/// <example>
/// <code title="Minimalist example">
/// &lt;state type="state" /&gt;
/// </code>
/// <code title="Full example">
/// &lt;state type="state" directory="C:\CCNetState" /&gt;
/// </code>
/// </example>
[ReflectorType("state")]
public class FileStateManager : IStateManager

And for the property:

/// <summary>
/// The directory to save the state file to.
/// </summary>
/// <version>1.0</version>
/// <default>The directory CCNet was launched from.</default>
[ReflectorProperty("directory", Required=false)]
public string StateFileDirectory

Where possible the document generator pulls the data from the attributes and property definition. For everything it tries to find the relevant doc comments – leaving them empty/blank if not found.

What do you think so far?

I’ll do one more post – how the document generator works from an external viewpoint, and how to get the documentation into the wiki.

1. Identify your users’ stories

As I studied users’ thoughts, I found patterns in what my project was really designed to do, above and beyond what the project brief said. I listened to what my mind was drawn to listen to. These were the users’ stories — what was most important in their working lives.

There are no right or wrong answers in listening. Be honest with your users that you’re there to add value to the way they work and their stories – needs, expectations, attitudes and capabilities – will become clear.

2. Embrace your users’ needs

Once I am aware of users’ needs, it is far easier to design according to them. When faced with a decision, I can compare it to their values by documentation as personas, and see it will bring me closer to a solution that is fit for them, rather than what is easiest for the project team to produce.

3. Accept expanding feature sets

A ZenAgile mind does not struggle. It accepts users’ needs as they truly are. A rock is a rock. It will remain that way no matter how much you worry, wish, or pressure it into changing. Worrying about requirements and ever expanding user wants are the same way. I accept requirements for what they are, do not waste time or energy fretting over it, and group them into feature sets for delivery in such a way that, as a whole, they add value to users’ work.

4. Energise for change

A ZenAgile mind can give you extra energy for change as you are not wasting energy fighting against the inevitable. As above, there is a large rock in your way. You have three options:

• run into the rock repeatedly
• agonize about the rock being in the way, or
• find a way around the rock.

Before ZenAgile, I chose the first two options. With ZenAgile, I now accept the rock for what it is: an obstacle. I accept that you cannot go through it. I do not panic, and waste time and energy worrying about the obstacle. Instead I make my own path around the obstacle, either over the rock, around the rock, or under the rock.

This is Seijaku (静寂) — the energised calm.

5. Enhance knowledge of yourself

As I practice ZenAgile, I spend a fair amount of time in conversation with others and thereby understanding myself and how I come to terms with change: change in the project context, changes in requirements, and changes that need to occur to the solution.

In time, I’ve learned to quiet my mind. I’ve listened to the same fears for projects repeating themselves which inspired me to change what was causing those fears. I’ve realised, for example, that lack of a user-centred approach was a large source of anxiety, and so it was time for a change. Without time to think and meditate on the conversations in a project, we tend to ignore what our mind is telling us, and remain locked into our old patterns of doing things.

6. Gain confidence in the agile way

As you reflect on your inner self, you become conscious of who you really are, your role, and the skills you bring to aspects of the agile project. You learn what makes you happy, what is beneficial to your project, and where you fit into the multidisciplinary team. You bypass the fears and anxieties of your mind, what role you play — Business Analyst, Project Manager, Information Architecture, User Experience Designer, Change Manager — and focus on doing what needs to be done. Boldly and passionately complete the iteration. The opinions of traditional organisations like PMI, IIBA, ABAA, etc, do not matter, because you know you are doing what is right.

7. Appreciate the iterative project lifecycle

I accept the project as it truly is – evolutionary in nature, rather than revolutionary. You will always uncover new aspects of users’ needs. You will always uncover the unknown as you proceed boldly through the project. Some will be surprises like a starry evening, a stroll by the river, or a night of solitude. Each will have their own unique characteristics to be appreciated. Mundane user needs also hold their own charm. Observing the quiet details of the project lends value to the less appealing aspects, and brings peace and joy in commonplace tasks.

8. Increase consideration for others

Each person on the project is interconnected. We are all searching for the solution, requirements, and a meaningful project to work on. It is much harder to be angry at the user who argues with you about scope when you realise they are on the same path, just at a different point in their journey.

9. Simplify your project and your documentation

Conversation not documentation helps you differentiate between needs and wants. To document things completely today is to suggest that it will fix users and their workplace in time until the project has been completed. By focussing, instead, on a minimalist, simple project solution delivered in a short period of time, with just enough documentation to describe the decisions made, you are able to deliver value to people now and then build upon that solution to meet their future needs.

This is Kanso (簡素) — simplicity and elimination of clutter from the project

10. Cultivate a giving spirit by mentoring others in the team

When you are doing your role in the best way you can, your heart fills with joy. You are doing what you were put on this earth to do, and doing it to the best of your ability. Your life is simple, you are living your values, and you have a clear mind. You can then give to others, mentoring and teaching with a loving spirit, to help them along their path.

This is the True Way of ZenAgile

M

I decided to go back to Vietnam a few months ago. I have an abundance of air miles that, for myriad reasons, I feel like using, my neighbors had recently relocated (back) to Saigon and it seemed like a nice little sojourn prior to the crazy that I know December will bring. Living in Hong Kong affords one the luxury of taking long weekends to places like Vietnam, Thailand, Taiwan, Macau, China… It is a great benefit. Having taken a long weekend in Bangkok not too long ago, Saigon was the perfect alternative. It would be warm, a great place to do my Christmas shopping, and I could help some friends out be being a pack mule for some of their stuff they were moving from HK in stages. So, I cashed in the miles, got the ticket and worked my way up to the departure date.

Tuesday evening while sharing a sampan with Frenchie, a former travel agent, we were discussing my departure 36 hours ahead.

“So, you got your visa, right?”
“On arrival.”
“Vietnam? I don’t think so. You need two photos, four days and some paperwork.”
“No, last time I did it on arrival.”
“I don’t think so, I mean, it has been five years for me, but I am pretty sure you need to get your visa.”

Shit. Shitshitshitshitshit.

I pulled out my passport. I certainly did not remember getting my visa ahead of time for Vietnam when I went in February… but I definitely DID remember getting it when I meant to go in 2006. I looked at my last Vietnam visa, perfunctorily dated the day PRIOR to my arrival. She was right. Of course I needed a visa to enter the SOCIALIST REPUBLIC OF VIETNAM. What. The. Fuck. had I been thinking? Of course, the point being I had NOT been thinking. I rarely worry about my visas. There are two really good reasons for this. The first reason is that I have an AMAZING travel agent who pretty much makes sure that I do not screw things like that up. (Ask for Daryl, you will not be sorry.) The second reason, and probably more to blame for this, is that I am American.

Doesn’t that blue passport get me everywhere?

People are always talking about how Americans are so arrogant. And so provincial. And so not-smart. And how they think they run the world. Etcetera. Etcetera. Etcetera. Provincial I am not. Smart… I will let you be the judge, if you know me, you already know my opinion on this matter. Running the world? Well, you know, you can only control what people allow you to control. Seriously. And while arrogance is a trait I espouse disregard for, I simultaneously find myself strangely drawn to it. [Note intentional juxtaposition of previous three statements.] Am I arrogant? I imagine a lot of people would say yes, but there are many things that can be mistaken for arrogance. [It takes an intuitive mind to see the difference.]

There are a surprising number of countries that do require visas of Americans. But since few of them are on the top 100 lists of places people want to visit, they are often over looked. Afghanistan. The Democratic Republic of the Congo. Sudan (though of ALL the people in the world, only if you are an American of Sudanese descent you can get a visa on entry…) Iraq. North Korea. Then there are places like Cuba, China, Cambodia and Laos where it seems clear that, as self-professed socialist states, a visa would be required by the likewise self-professed disseminators of democracy. Oh, yeah, and THE SOCIALIST REPUBLIC OF VIETNAM.

After feeling pretty silly for having over looked this totally obvious issue of the entry visas, the next step was deciding what I would do. It was 10:30 pm on Tuesday night. I was set to fly at 9:00 am on Thanksgiving Thursday. What to do? After considering what story I would tell in order to avoid looking completely stupid, Google, of course. Enter Vietnam-Visa.com. American passport holders are able to get a visa on entry it said. No way! [It is this sort of thing that perpetuates the existence of all the things that people hate about Americans, btw.] I filled in the form and paid US$21. And then guessed I would have to wait and see what would happen.

I did not look forward to admitting that I had made this mistake when people asked why I was NOT in Vietnam over the next few days, but the more I thought about it, a few days at home didn’t sound so bad. I became surprisingly detached from the outcome of this ordeal and just laughed at the way things go sometimes.

I went to bed.

When I got up the next morning I bumped into my neighbors who look after my cats when I travel and told them I might not need their help because I had done something so embarrassing.

“What’s that?”
“I forgot about my visa. I feel so dumb.”
“Oh stop! Who hasn’t done that?”
– wait, really?– She didn’t roll her eyes and acknowledge my idiocy. It was just, like, no big thing.

I smiled.

I called my parents on the way to yoga and told them the story. It was out of my hands, but I would know by 6 p.m. the day before I was supposed to travel if I would in fact be traveling. It was not so bad to admit it after all. I told my yoga studio that I didn’t think I would be in class on Thursday because I was supposed to be traveling but that I had forgotten about my visa so I might be there after all. They laughed and said they hoped they didn’t see me, but would hold a place for me anyhow. But they didn’t laugh AT me, just with me. Realizing that the issue I had about the visa was little to do with the actual issue and all about my embarrassment for being an idiot made the situation a totally different thing. I didn’t need to be in Vietnam for any reason, it would be nice to go, but I would go another time if this didn’t work out. I called Cathay and told them the situation and they told me that the reward ticket could easily be changed if it was not used. I called my hotel and told them what was up and they said no problem, just to let them know, there would be no cancellation fee.

I told my co-worker about all this and he said, “You live a charmed life.”

That may be so. But it certainly does not go without appreciation.

And then I got the visa.

At 4:00 p.m. I received an email with a letter attached saying that all I needed would be two passport sized photos, my valid US passport and US$25 and I was set to enter the Socialist Republic of Vietnam. Just like that.

I woke up on Thanksgiving morning and packed my bag and headed out the Airport Express, where I got my train ticket, checked in my baggage, and got my passport photos all within about 20 meters. In less than ten minutes. It was that easy.

And so my worst habits have all been reinforced. With one little change: an American passport and a smile may open a lot of doors, but it is complete detachment from the expectation of what might lay on the other side of those doors – as well as from the reality that sometimes the door might not open – that makes all the difference.

Happy Thanksgiving from Saigon.

A performance appraisal is one of the best and most important ways to recognize a person. When you recognize people in this way you accomplish two objectives. You let the person know how you feel about him and you provide a permanent documentation of the recognition. The documentation will be important to the person’s future growth and advancement within the company.

When you recognize a person through the performance appraisal, make sure you provide as complete a list as possible of his major accomplishments. As you note the accomplishments, be specific. A person who is unfamiliar with the work of the area should be able to read the appraisal and get a fairly complete picture of the person’s accomplishments.

My Consultancy–Asif J. Mir - Management Consultant–transforms organizations where people have the freedom to be creative, a place that brings out the best in everybody–an open, fair place where people have a sense that what they do matters. For details please visit www.asifjmir.com, and my Lectures.