poniedziałek, 20 sierpnia 2007

Technical Documentation Generation

When you create the big software solution, you usually need the technical documentation. Since some time there exists the automated documentation builders like NDoc. As I had some previous experiences in VS.Net 2003 (.Net 1.1), I was quite sure it will be nice and quick task to do the thing. How big my surprise was, that new technologies does not always make people live easier! :)

Basic NDoc is no longer supported for VS.Net 2005! The last NDoc version 1.3.1 does not work for .Net 2.0. There is some way to change the configuration file, so .Net 2.0 solutions are supported, but this is rather workaround than a complex solution.

I decide to look for some other new “mainstream” solution and I have installed the Sandcastle, especially that there is quite a number of fellows talking about the solution – among others Tomasz Kopacz, who is local, polish tech guru. The main page to start exploring the whole topic is not so popular on Google search. Sandcastle has surprised me because it does not provide you the GUI within the main package and you must download some additional tool for it like the Sandcastle Help File Builder. Unfortunately there is the other back fire and you must have generated xml file with comments (XmlCommentsPath), which was not necessary in old good NDoc! There is some nice project, explaining the basics, however it supposed to be some simple task!

As expected, I am not the only one who has this type of problem and there is number of places, where this discussion repeats – Joel on Software is one of them. I started to look for some other solutions, but most of them like DocumentX or Doc-O-Matic are not for free. Doxygen looks quite odd. And then the whole loop closed…

NDoc 2.0 Alpha, published by Kyno Sarges, who truly did the tremendous job seems to be so far the best option for old NDoc fellows. It is quite sad that NDoc home page is DEAD and you must to look for the remedy in such a places, but it works. It beats Sandcastle definitely and furthermore it provides you the comments’ xml file as well, but the difference is IT IS OPTIONAL! Unfortunately it is no longer possible to consume the whole solution file and have the documentation ready in a minute, but… at least you can do something quickly, without the necessity of writing custom files per project.

There is a good document, which described most of common problems with NDoc2 Alpha. The major problem is though that NDoc2 is no longer supported! Dead body again :) There is also the other drawback - unlike in NDoc 1.3.1 you must generate the xml comment file for each project separately (!) and add it to compilation in order to get summary and parameters tags consumed. How to make a trick is described in details in the article and the other one. The positive thing is that you can easily switch on one the parameters so the final chm document shows you in read which summary or parameter is missing the content of the comment and in such a way you can easily find the places in code to fill in.

So this is how the whole story finishes – there is one thing, which I sure of. Creating technical documentation for software solutions takes now much more time and effort than it did before! :)
My programmers finally have chosen the Sandcastle as it is the only one supported by the Microsoft and they have convinced me. I am just after the second review of the generated technical documentation and I love the options showing on red what is missing ;)

piątek, 17 sierpnia 2007

Understanding Public-Key Infrastructure - Carlisle Adams, Steve Lloyd

The book is one of not too many, complex publication about PKI. It starts from explaining the asymmetric encryption idea and why such a solution is better than a symmetric encryption; this part includes also the general description of the most popular algorithms for both symmetric and asymmetric method. Then it describes quite clearly what kind of infrastructure is necessary to provide such solution and how it works. There are also mentioned the most popular services, issues and decisions linked with the PKI.

The content
The very strong positive aspect of the book is the practical approach. On page 59 it describes in details the full range of services within the PKI Infrastructure (Table 5.1), but there are also 4 other variants, where just the subset is implemented.

The chapter VII describes in details all the procedures implemented by the PKI like the Initiation, issuing, revocation plus renewing and archiving. It discuss also the communication with CA (Certificate Authority) and eventual use of RC (Registration Center). It covers also the transportation issues of public key where following solutions are possible:
· Publication out-of-band via the external channels
· To and from the public storages and databases, which provides them on the request and update in real time
· Network transport with communication protocols like secured email (S/MIME)

Chapter VIII on page 107 starts discussion about the various CRL implementations including distributed, delta CRLs and CRT tree. The description includes enlisting the benefits comparing to the basic solutions. The chapter describe also the OCSP solution, which provides the on-line and real-time solution on the top of CRL.

Chapter IX contains the interesting review of trust models. At looks like the unnecessary topic, but in fact it provides the input for quite important decisions about the shape of CA tree. Tree is in fact just the first considered model, where the next ones are based in general on cross-trust mechanisms (distributed trust).

The chapter X contains interesting discussion about the necessity of use number of key pairs for various applications and it mention SEIS (Secured Electronic Information in Society) regulations suggesting three of them:
· For encrypting and decrypting
· For signing and verification of users identity for general purpose
· For signing and verification of users identity where uniqueness of identity is the must
And it also covers the options about the storages for certificates, where LDAP is the most popular.

Chapter XXI will be great help if you need to convince decision maker about the necessity of using PKI. The most popular applications are described right there. When you start to implement the solution XXII will be at great help as all the major questions are there enlisted.

The book explains in details how the PKI works. I must say, that understanding the asymmetric idea, I still had a problem with understanding what for exactly the private and public key are used and how the whole thing works. There is no too many publication which explains in details and in practice how the infrastructure works – the book does it. It is a great starter for anybody involved within the PKI project as a user, project manager, programmer, supporter or team mate.

Also most of the topics around are covered including the legal issue (however it says just about US legislations).

It also shows the biggest problems linked with PKI solution putting a stress especially on decisions flexibility versus security. Number of problems may be solved with usage of the solution, but there is no golden rules and must to follow procedures. Most of things mentioned in the book must be customized per particular company and application.

Score: 4 (good) /6

sobota, 11 sierpnia 2007

Windows Live

Mood: Bored

When I have visited http://www.live.com/ my first impression was: “Microsoft finally fights Google back and tries to deliver the similar set of rich services like Google". Actually I am still surprised that number of my collegues still does not know about iGoogle, which allows you to create easily the rich start page like the one below:
Live.com has the same approach and it is the next face of MSN Search and it is mainly Microsoft’s search engine, which has the ambition to compete with the Google Search. The service increases its share from 8,9% in February to 13,3% in June in search market according to Nielsen//Net Ratings. There is however, the other interesting thing happening in here, as live.com is also a new face of start.com.

Let’s explore :) what is inside.

First page
The first page allows you to create your own matrix of gadgets including the things like:
  • Preview hotmail email account
  • Weather
  • Windows Live One Care (after installing additional software)
  • RSS feeds
The way of using some of these things is not straightforward. For example you must first add the weather gadget before you can change the cities displayed. On the other side the whole thing looks quite neat and provides in the list even smaller towns from Poland like Włocławek, which is a town with 123k citizens. My only question is… what means these postfixes like MA, WP, KP – I could not find it easily? Anyway… cool thing coming from quite interesting Foreca service, which is definitely beating the weather service attached to iGoogle!

The RSS feeds are more user-friendly. First of all you have the whole set of ready to use !LOCAL! news services. It is truly unique experience to see in the service like this about 10 major polish news sources. There was also not a problem to link to the other RSS feeds, however unfortunately you need to know the exact link to add to the text box – there is no option to search for RSS feeds and add it (you can find, but you can not add).

Anyway after no more than 15 minutes, doing the One Care scan in the background, I could create my morning news paper looking like:
There is a number also the number of small, useful things like:
  • You can change the name of the tag (including national characters)
  • Menus
  • As you can see, there is nice “popup” showing you the details of the article
  • Except adding additional blocks with content (gadgets or RSS feeds), you may also add additional pages and manage all the things quite easily.
  • All the elements may be moved by drag and drop and number of columns may be changed
  • You can publish the page or the whole thing and Windows Live will provide you the public link to your page and/or the option to send it to your friends by email
  • In each feed you may define the number of headers

The whole thing is based on DHTML and java script, without any fancy graphic, so it is working quickly and smoothly. There are some moments when your browser does not behave as it should (see below), but it does not happen often and you may live :) with it.


The Windows Live provides also the possibility to add OPML file (OPML stand for Outline Processor Markup Language). It is targeted at iGoogle users, who wants to move all their feeds into Live.com. They can export these feeds with OPML Export gadget and then import them in Windows Live. Unfortunately the gadget did not work for me in iGoogle. Funny thing is though that Windows Live does not provide the option to add new gadgets, so in effect, you may only import OPML file, but there is no option to export it. Is it done in purpose?

Other solutions

Considering this thing as “your start page” in internet, except the iGoogle, there is also the other quite interesting polish project called iloggo. It is kind of the shell around the Google search, which allows you to display the sets of your favorite links as the pictures. Worth to see at least the video on you tube.

The most amazing thing, which I have seen lastly is however the PageFlakes service. First of all it configures the interesting start page for you in 5 minutes and you do not need to provide any email address to register! Furthermore as you can see below the content is very rich and personalized for the country:

The service won Web 2.0 award in 2006 year beating Live.com. The only thing where Live com seems to be better is the bigger range of languages available, but the whole thing is much cooler and working more smoothly plus the range of additional widgets is much richer than in Live.com

Other Live Services

Except “your start page” there is also the big number of the other on-going beta projects like for example Windows Live Gallery. Its name is a little bit misleading and it has nothing in common with the Google’s Picasa Web Albums project. Live Gallery provides you the access to very various content like gadgets, icons and pictures.

Unfortunately, there is a lot of mess around – commercials, GUI far from MS standards, many things in one bucket and each provided item has a different style.

When you do the presentations, web pages or applications, there is a common, general problem to find the set of graphics with one style – the service would be a perfect shot to fix the problem, but unfortunately it is a lost chance. For now it is simply the next, silly bucket with “cool” items for kids.

Except Live Gallery, Microsoft tries also to sell for the next time the Messenger, Spaces and Toolbar. Unfortunately, despite I try and I try and I try, I cannot see the big picture as I do, when I am looking at Google Services. Live Services seems to be the cry that MSN idea did work out. Microsoft THINKS now, what to do with all these things, trying to pack them under the Live Services brand, but it will not work out. I truly hope that following months will show that Microsoft has some consistent vision of Live Services, which will be something more that just a new version of Messenger and Spaces. The live.com is the light in the tunnel (I am not visiting iGoogle, but I may visit live.com from time to time) and I hope that it is leading to the place where Google Services truly will have some competitor.

Funny feeling to write all of these things in Google blog service :)

poniedziałek, 6 sierpnia 2007

"Leadership the challenge" - book review

Mood: Relaxed
Soundtrack: I am easy like Sunday morning


The book tries to be the ready to use recipe for the success by being the superior leader. The whole story is based on the axis of 5 practices and 10 commitments enlisted on page 22:
  • Model the way – Find your inner voice, Be the example of the shared values
  • Inspire a Shared Vision – Envision, enlist others in a common vision
  • Challenge the Process – seek for innovations, search for constant small improvements
  • Enable Others to Act – promote cooperative goals and building the trust, strengthen others
  • Encourage the Heart – appreciate individual experience, celebrate the values and victories
Each of these things are described in details in the following chapters with big number of real stories and examples.

The body

The 5 practises, seems to be a little bit pumped up and the best part of the books are actually short stories and tactics rather than “way of living”. The book says in number of places, as on the page 99, that leading by the story telling is very useful and practical technique. Page 381 mentions the David Amstrong’s book, which contains the collection of
“285 stories […] organized around the themes such as “stories that kick start
urgency”, “stories to make people brave and wise”, “stories about core values”,
“stories to inspire innovation””!
The book tries to be something more, but in fact, it seems that is the competitor of that book.

Instead of describe each practice or commitment, I will describe the best stories and tactics. The stories will be scored:
1 is I need to mention it, but nothing else
3 is I need to remember it
5 is Good story
7 is Very good story
9 is Excellent story

The stories

Lindsay’s story about the customer service – page 5; score 5
Lindsay highly improved the customer service in repair vehicles sector (women manager in man world) – couple of weeks after reading the book I remember the sample of the worker who drove hundreds of kilometers to pass the repaired car to the customer. Oh Lord, how much I would love to be their customer! The morale of the story is quite trivial: “it is always about the people”… way it is still forgotten?

Szwarzkopf’s story about the team-building – page 87; score 6
The story is about the new recruits coming into the base. The experienced officer “looking like from Olympics”, run with his team much more than the recruiters used to. The effect is that recruiters run much behind the leader. Szwarzkopf takes the officer on a side and explains him how the new soldiers feels like – they are first day in a new place, first morning run, they try to do us much as they can, then they try more, then they try even harder and they their lungs can not keep the tempo… Their leader, their officer does not even look behind. Where is the team spirit? Where is the unit cohesion? Of course, Szwarzkopf is successful in his couching action and he can see “the light dawned on the captain’s face”. He knew also that “the episode would get talked about around the base”. Ehhh… soldiers :)

Treyz’s Disney story about baking the client – page 88; score 8
Treyz speaks about the ABC-Disney negotiations. Negotiations were hard and long. What unique has happened in here was the personalized customer treatment. During on-going negotiations, Walt Disney (the president) took the Treyz’s wife Janet for whole-day-long personal tour guide to the Disneyland and after the amazing day, he provided Treyz’s kids the personalized gifts (among others Pinochio). The whole effort paid back triple during the on-going ABC-Disney negotiations (Janet convinced the husband to do the deal), couple of years later during the next and the next deal. The power of the personalized customer treatment is proved as nowhere else.

Geof Yang’s story “Vision for the leader is like the vision for the driver” – page 113; score 7
“Imagine you are driving along the Pacific Coast High-way heading south from San Franciso on a bright, sunny day. The hills are on your left; the ocean, on your right. On some curves, the cliffs plunge several hundred feet to the water. You can see for miles and miles” – you have vision, “you are cruising along at the speed limit”.
“Suddenly, without warning, you come around a bend in the road and there’s blanket of fog as thick as you’ve ever seen it”. What do you do? […] I slow way down” – well, you would be stupid to drive fast if you have no vision.

Janus effect – page 119; score 6
When drawing the vision, if you look first on your rear-view mirror you feel much more confident about the future predictions. There is a table 5.1 giving you some hard numbers for it – people asked about prediction gave you on average 3.2 years timeframe instead of to 1.8 years. Before making any vision, think for a while how the previous, similar project in the company or somewhere else looked like!

King’s speech “I have a dream” quoted at page 146; score 7
The whole speech is quoted. Before reading it, I though it is the exaggeration, but during and after… It is truly a great speech.

Ritz’s daily lineup meeting at page 180; score 5
Quick 15 minutes meeting is one of the key points for the agile methodologies. It is funny thing to see it in the Ritz chain across the whole glob. Funny and teaching… and making you to remember to keep the routine done, wherever you are and regardless from the size of your team.

Physicians story about listening more than speaking at page 187; score 9
“The Journal of the American Medical Associations reported on a five-year investigation of why some doctors were sued, and the others not, by parents who had all experienced the same tragedy (the death of their child during childbirth). […] “Physicians who had been sued frequently were perceived by their parents as unavailable, rushed, unconcerned, and poor communicators, while physicians with no malpractice claims were perceived as most available, interested, through, and willing to provide the information and answer questions fully.” Clearly, listening deeply makes a difference.”
If the kid asks why the man has two ears and one mouth, it is the answer. If you are not sure if you keep the proper listen/talk ratio ask somebody about noting it, during some longer meeting.

Urban’s ski story “you must fail to learn” at page 215; score 10
It was the first day of skiing classes. I skied all day
long, and I didn’t fall down once. […] I skied up to the ski instructor, and I
told him of my great day. […] He told me, “Personally, Urban, I think you had a
lousy day […] If you are not falling, you are not learning
Desmond Tutu incremental approach at page 228; score 3
“You can’t eat the elephant with one bite” and if you count 100 cards it seem to take much more effort comparing to counting 10 times 10 cards.

Axelrod strategy at page 254; score 10
“Two parties (individual or groups) are confronted […] they must decide whether or not to cooperate […] There are two basic strategies -cooperate or compete - and four possible outcomes based on the choices players make-win-lose, lose-win, lose-lose, win-win […] The long term winner was the simplest of all strategies submitted: Cooperate on the first move and then do whatever the other players did on the previous move.” – that is truly the first strategy which seems to may work within the rat-race!

Elliot Aronson Jigsaw groups at page 270; score 3
That is about the academic experiment, which have been divided into 5-6 groups of 5-6 students. Each group is working of some sub-part of the whole topic and then it shares the gathered knowledge with the others. “The results are dramatic […] All students do as well or better in their knowledge, the lowest-performing students do significantly better […] the levels of cooperation, self-esteem, compassion, and tolerance increase.”

Joseph Sensenbrenner’s story “It is their duty” at page 289; score 4
In big organization there is often the big bureaucracy problem. The story is about “the fleet with 440 different types, makes, models, and years of equipment”. That happens because the purchase department bought the cheapest vehicles, which were not the cheapest in maintenance, but parts manager could not change it because “[…]controller wouldn’t let us do it” And the controller?” says it is about the attorney… who says it is not a problem if you make strong and clear specification. Joseph changed the flawed system involving the frontline employees and 24 steps purchasing policy was cut to three. Everything would be truly a cool story, unless the whole thing had to be done by the mayor and none first-line employee including the controller could do the thing.

John H. Stanford story about the key to the success at page 399; score 4
Stay in love
The tactics

Other key things, which are something more that just well rounded sentences:
  1. Provide, improve and maintain the two-way communication (page 283), including some practical implementations:
    · a 360 degree feedback mentioned at page 85 and 103 – unfortunately it is just mentioned; no word how to realize it in details (the routines, sample set of questions etc.)
    · the collaboration audit (the only template of the form in the whole book!) form presented at page 267.
    · Passion-compassion game mentioned at page 375; where one person’s role is to speak in passioned way and second’s person role is to listen compassion.
  2. People want leaders who are honest, forward-looking, competent and inspiring (page 111). It is trivial, but important thing is that these are these adjectives and not the others (e.g. funny, self-confident, generous etc.) - worth to remember.
  3. Engage others in planning and analysis (page 142) – it also seems trivial, but many people paid a lot for the lesson, that usually teamwork is better than single heroic effort. It is described well within the Chinese wisdom (page 182): “Tell me, I may listen. Teach me, I may remember. Involve me, I will do it.”
  4. There are some useful tips about how to make public speeches at page 184-185 and advices like:
    “don’t say try, say will and are”
    - Do presentation workshops (including video taping), if you feel it is your weak point – there is a lot of people who has a problem with it and you must not be ashamed if you do
    - You must be enthusiastic, emotional, expressive and personally excited
    - Speak clearly and quickly
    - Make eye contact
  5. “Challenge a process” at page 177 is the story, which I have heard from my colleague from Toyota Bank in Poland – amazing thing, they can achieve really high cost reduction, by making really small (even micro) changes on the production lines. Saving pennies at actions, which happens hundred times daily, can make you saving million bugs monthly and I found exactly the same story in the book (at page 228-229) side by number of the others practical samples:
    - “Pick one major project per quarter. Implement one smaller improvement every three weeks” – page 196.
    ”Eliminate the Dumb Things”. Go find what needs fixing in your organization.
    Wander around the plant, the store, the branch, the halls or the office. Look
    for things that don’t seem right. Ask questions. Probe.
  6. Routine paradox at page 189 – on one hand you want to have one big routine, the process and simple production line on the other hand you must to try making it better, make you and people having fun (page 198, 367; there is even a book “301 Ways to have fun at work” mentioned at page 367) when they work and do some innovative things to keep creativity (page 197). The balance is the best approach.
  7. Let ideas flowing from the outside” at page 193 is definitely a good approach.
  8. Treat every new assignment as a start-over” – page 185
  9. Add a new member or two to the group every couple of years. Rotate some people out and others in.” at page 201 – keep pumping the fresh blood into company’s veins.
  10. Gather the ideas and give the awards for the best ideas – page 202
  11. The weakest muscle in the body is the one between the ears” page 207 – do not let yourself to think that some limitations or beliefs are stronger than you; implement incremental approach in order to achieve the big things. Lu Ann Sullivan at Wells Fargo Bank (page 212) established individual weekly goals and in this way, he could achieve the big win at the end for the whole branch (managing by targets).
  12. Collect yeses” - page 232. Tring to find common point is actually kind of NLP method, which causes very quick connection line and improves the communication between persons.
  13. Conduct pre- and postmortems for every project” at page 234
  14. Rotate team meeting leadership so everyone gets a turn” at page 277; “rotate the chair responsibility” at page 307
  15. Personalize cubicles and award the best ones. It makes people more tied with the work plus the variety makes the workplace special – page 333. Google is quite well-known from doing it at their offices.
  16. Do ceremonies for successful people and make them recognizable – page 345. Make the public board, where you can put the public “award notes” for the employee of the month – page 373. Picking up “the employee of the month” is the challenge itself described at page 377 as looking for “extra mile heroes” by ALL the employees. This action causes the extra achievements histories spread across the organization loudly by the employees themselves.
  17. Be the cheer-manager, the cheerleader among your team – the person who is heating up the team for fight. Do not be afraid to say people thank you if they did a good job – page 345.

The Opinion

All the items mentioned above and number of quotations direct to the conclusion that the book is really cool and practical. Indeed there are fragments where it is, but unfortunately the major part of the book is simple the bubble talk like the one at the page 123 where you find out that you MUST (the word used very often in the book) to listen, read, smell, feel,taste etc. Well… of course you always must to use all of your 7 senses :)

There too many places where you, as a leader, has to be the kind of the saint Santa Claus, who share, cherish and take care of his team mates :) The truth is that the leadership is often about the sweet, stress and all the dirty things, which are not mentioned in the book at all. What about the rat race, which was the plague some time ago and there are still companies which focus on the brilliant individual and not on the team collaboration skills? The “clean laboratory environment” does not surprise actually, as the authors of the book are working for the Leavey School and not for some big corporation, where they could find all of these things. They interviewed number of people, but who washes dirty laundry publicly?

The other problem within the book is that number of sample stories applies to high executives. There is a fragment at the end of the book, which says that anyone can be the leader, but how does it go along with the Joseph Sensenbrenner’s story “It is their duty”. I do not believe that front line employee could change the change in the story. Unfortunately, many stories are told by the chairmen, CTOs and generals – they could do some of the big changes, because they had a power to do it.

The biggest concern is however that unlike “The 7 Habits of Highly Effective People” the book does not give the full and complex recipe. It seems like the authors collected the very rich set of samples, stories and tactics, but then they did not know what to do with it. Even the proposed way of cataloging them does not seem to work as the same thing is repeated often number of times in various places of the book. Unlike “The 7 Habits …” it does not say also anything about the private life. Can there be the successful professional leader, who is passive in private life?

The book is a big, lost chance to say something more than the bunch of good stories and interesting tactics.

Score: 4(good) /6

web metrics