Posts Tagged ‘best practice’

Be a better blogger – Add a Summary Sentence

Adding a summary sentence to the top of a blog post helps a reader decide if they want to stay and read your post.

My team took a great course on writing for the web where we learned a number of tips and techniques to improve our blogs. I want to share some of what we learned so you can be a better blogger

The average user spends 10 seconds looking at a web page before they decide if they want to stay and read it. That means you have 10 seconds to convince them they want to read your post. Now having said that, not every post is intended for every reader. When I write a blog post about the Imagine Cup competition it is aimed at university and college students taking Computer Science or Engineering. Whereas this blog post is aimed at bloggers. You don’t need to hook all readers, just your intended audience.

The easiest way to tell someone in 10 seconds or less what is in your blog, is by adding a summary sentence. I find putting it in a different font size or color helps it stand out.

Don’t believe me? Test it out

Look at this blog post for 10 seconds. Do you know what you will learn if you take the time to read that blog in full? Was 10 seconds enough time for you to make a good decision as to whether you want to read that blog?

Now look at this one. A little intro paragraph at the beginning helps doesn’t it?

Now look at this one. See how the opening two lines give you enough information to decide if this blog is of interest to you?

Now look at the first sentence of the blog post you are reading right now, did that sentence catch your eye? Did it help you understand what you would learn by reading this post?

It doesn’t take long and your readers will appreciate it!

Advertisements

Do you hate SharePoint? Part 4 of 4

If the answer is yes, could your hatred be caused by your local implementation? In this final post of our blog series we look at the last of four common problems with SharePoint implementations and how you can address them.

Once again, a huge thank you to Neil MacIsaac, SharePoint MCT, for putting this entire series together. Happy reading!

If you missed the earlier posts you can find them here

  1. Business Intelligence

This week we look at Business Intelligence.

4. Business Intelligence

Are there organizations out there that are really striving for Business Unintelligence? Wouldn’t everything that an organization does be in an effort to do something better? I love the term Business Intelligence (BI) mainly because of its massive overuse and its wide misunderstanding as ‘reporting’. So the question really becomes "How do we maximize our BI?" First, it is important to understand what BI really is. It is about making better decisions. If we have better data, and a better understanding of our data, it would be logical to conclude we would make better decisions right? Not necessarily. The theory is correct, but in practice most organizations fail to implement this properly by not focusing on the decision that they are trying to improve and instead only achieve in bombarding their key decision makers with an avalanche of reports. What is also surprising is that most of the decision makers in an organization are probably the ones asking for the reports in the first place. Let me give you an example. In a sales based business, you might see some monthly sales figures like this (overly simplified for the sake of discussion)

Sales Member

Monthly Sales (Units)

John

5,437

Mary

8,350

Bob

3,043

Jim

7,410

Why do we need to see these sales figures? The typical answer you will get will be "Because I need to know if there are any problems and to see if we are doing better or worse than last month or last year." So, with the above numbers, where is the problem? Most people would focus on Bob because his numbers are lower than the others. What isn’t shown with these numbers is that Bob is the newest of team and manages the smallest sales area. Can you still spot where the problem is in the above sales numbers? The typical failure in implementing a BI solution within SharePoint is usually in the disregard for a proper BI solution that focuses on those key decisions which strives to achieve a better decision by supplying as much data around the factors and drivers of the data as the data itself. Instead we see fancier reports of the above sales table and hope that our decision makers will ‘figure it out’. Another interesting point concerning SharePoint and BI integration is the potential for SharePoint to implement the decision. If our BI solution is focused on key decisions, a good solution should allow the user to implement the decision as quickly and easily as possible.

Conclusion

As you can see, SharePoint offers many challenges when deployed into an organization and requires due diligence to maximize your return. I hope that some of my tips may make their way into your organization and perhaps save you from some of the common pitfalls that have trapped others. There is good reason why SharePoint has become as popular as it has and hopefully you will be better able to get the most out of your implementation.

Do you hate SharePoint? Part 3 of 4

If the answer is yes, could your hatred be caused by your local implementation? In this blog series we look at four common problems with SharePoint implementations and how you can address them.

We continue our series by Neil McIsaac, SharePoint MCT, for putting this together. Happy reading! If you missed it you can still read Part 1 and Part 2 of the series

SharePoint is an interesting platform and as it grows as a product and with its already incredible adoption, it is an important cornerstone for many organizations. But ask the people that work with it, and you will find a divided love it or hate it passion for the product.

Why hate it?

It’s my experience (which dates back to the site server/dashboard days), that many customers have difficulty handling the product and I mean this a number of ways. Here’s the issue:

SharePoint will amplify your problems.

So why do we hate it? I would hate anything that made my problems larger. But did SharePoint create the problem? That would be like blaming the carpenters hammer for building a crooked house. The problems are our own doing in the majority of cases. In my experience, the most common problem SharePoint seems to amplify are the following;

  1. Information Security
  2. Business Intelligence

This week we look at Information Security.

3. Information Security

SharePoint has a confusing security architecture. A friend of mine continually jokes that you can do anything in SharePoint, as long as you know the 6 strategically placed security settings you need to set to allow users to interact with your content. I like to keep things simple. I always start addressing security by asking these 3 basic questions;

What are the requirements?

This question is pretty straight forward and we do it relatively well. Who gets access, and who doesn’t.

How do we know we meet the security requirements?

This is one area where SharePoint poses some difficulty, since it lacks any worthwhile reporting tools and has enough security layers that are hidden in the UI that it feels like finding an answer to this question is akin to finding the meaning of life itself. Paired with the products inability to properly handle security inheritance and the lack of a proper method to deny permissions and you are on a never ending hunt for individualized permissions. Yuck. Unfortunately the best security reporting tools are third party. Your team needs to sit down and address how your organization will address security reporting and auditing.

When is the last time we checked?

Security audits are often checked at implementation, but rarely checked afterwards. Permission elevation happens for various reasons such as troubleshooting, making it necessary to schedule our audits. If running an audit is painful because we haven’t properly addressed the above question, then scheduling it will hurt that much more. Again, get a good security tool.

Information Security Tips

Here are a few tips on implementing security in SharePoint to help make things a little more manageable.

Libraries/Lists are for security

I am not a fan of the Shared Documents Library which comes as a default. If you have ever heard me talk on the subject, you know I get a bit worked up about it. I am a fan of lists/libraries in SharePoint and I completely understand Microsoft’s position in adding it. It was a necessary evil. The problem that I have with it is what most people put in it. It goes against pretty much every information management principal that we have. Many organizations use this library and why not? It says "Shared" and I want to share my stuff, so why not? The reasons are many, but at a simple level, you will end up with a folder structure that mimics your old file shares, and make it work by placing individual permissions on folders and files to compensate for your lack of proper architecture. If you think of lists and libraries as containers, which if you were paying attention in the previous blog post when I ranted about the importance of structure, you can shape these containers to better store its information. You can change the shape (think ‘content types’), and you can change the behaviour (think ‘workflows’ and ‘views’) to better aid the end user in the task they have at hand (think ‘Use Cases’). Coming back to permissions, if we have a container with similar information in it, we can control permissions to all of its content by controlling permissions to the container. In other words, permissions in SharePoint are best handled at the list and library level and not at the folder or file/item level. Which brings me to a solid point: If you are not sure how many libraries you should have, look at the common permissions to your content. If a group of people need read access to one type of content but not to another type of content, then the content should be in the same list/library and we can control permissions to the content by setting the permissions once on the list or library. So how many lists or libraries should you have? The answer is in how many groups of content with the same permissions you have. This is not always the answer, but it is a good starting point.

Use SharePoint groups as functional roles

SharePoint groups are best used to reflect functionality rather than entity. Since we typically use Active Directory groups, adding the AD groups to our SharePoint groups to reflect the same group would be redundant. For example, having a Sales group in AD, which we mimic and create a Sales group in SharePoint usually offers little benefit. Having a group in SharePoint that reflects their ability is preferred. For example, I can create a group in SharePoint called Sales Lead Generators that can better reflect what anyone in that group can ‘do’ rather than who they are. Not only does it simplify security administration, it makes audit reporting a lot easier to read and verify.

Use Information Rights Management

Information Rights Management has been around for some time now. Surprisingly, most organizations that want to secure documents rely on securing the folder or physical media where the file is stored. The problem is that this security simply doesn’t follow the document where ever it goes. IRM on the other hand, does! You just have to ask someone if their documents are just as secure after an employee that has proper permissions to the file copies it to a thumb drive, or inadvertently emails it to the wrong person. SharePoint and IRM integrate very well. You can check out more about IRM here.

Next week, part 4 business intelligence…

Do you hate SharePoint? Part 1 of 4

If the answer is yes, could your hatred be caused by your local implementation? In this blog series we look at four common problems with SharePoint implementations and how you can address them.

SharePoint is one of those tools where the line blurs between the developer and the administrator, much like SQL Server and much like SQL Server, SharePoint is everywhere! So even though this post is not about coding for SharePoint, I thought it had some great information that many of us could use when dealing with SharePoint implementations, either as a developer supporting an implementation, or even as an end user (did I mention I use SharePoint at work? Hey boss, you reading this?).  A huge thank you to Neil McIsaac, SharePoint trainer extraordinaire, (bio at the end of the blog) for putting this together. Happy reading!

SharePoint is an interesting platform and as it grows as a product and with its already incredible adoption, it is an important cornerstone for many organizations. But ask the people that work with it, and you will find a divided love it or hate it passion for the product.

Why hate it?

It’s my experience (which dates back to the site server/dashboard days), that many customers have difficulty handling the product and I mean this a number of ways. Here’s the issue:

SharePoint will amplify your problems.

So why do we hate it? I would hate anything that made my problems larger. But did SharePoint create the problem? That would be like blaming the carpenters hammer for building a crooked house. The problems are our own doing in the majority of cases. In my experience, the most common problem SharePoint seems to amplify are the following;

  1. Information Management
  2. Project Management
  3. Information Security
  4. Business Intelligence

Without a doubt, this is not a definitive list of problem areas, but from my experience, these are the key ones that help make or break your experience with SharePoint. So let’s take a look at them.

1. Information Management

In my mind, this is the biggest problem area and by a considerable margin. Why? Well, if you think about information management, it really encompasses all of the other areas. It is a really broad topic. What is surprising is as an industry whose core revolves around titles such as Information Management and Information Technology; you would think that we’d be better at it. Let’s look at an example: The shared documents library within the default team site is fairly widely used by organizations. At face value it seems like a perfect solution for the sharing of documents. After all, it is called the ‘shared documents’ library.

When I was a kid, I remember going to the library. I am talking about the real one that had shelves and shelves of books that you couldn’t carry around in your pocket. I won’t refer to those times as ‘the good old days’ because they simply weren’t. What fascinated me was the organization. I had the power as a kid, to walk in to the library and find various books on a topic that interested me, and to browse some additional information about each book before ever finding the book on the shelf. You might be thinking that I am referring to the ability to sit down in front of a computer and search, but I’m older than that. I’m referring to the cataloguing system called the Dewey Decimal system.

That’s right, no computers. Yet I could search amongst a huge amount of material systematically and rapidly (for the times). 135 years later, and I’m watching organizations fumble with taxonomy and metadata like new borns driving a car.

So what’s the problem?

If we look at the shared documents library like a real library and a document like a book, if you let your employees simply start saving their document in the library it becomes almost the equivalent of having a library where you open up the front door, and chuck your book into the building. Imagine trying to find that book a week later. For the first hundred books or so, you might be ok, but what about the first thousand? Every time you see the default shared documents library being used, you should picture a real library, with nothing more than a mound of books in the middle of the room and people frantically trying to find things in the pile. The first thing that might come to many peoples mind is that "Well that is what we have Search for!" No we don’t. Well, not exactly. Search doesn’t organize our data for us; it makes the retrieval faster in larger systems. If you don’t believe me, do an internet search for a topic such as Shakespeare and tell me what the most current and correct material is on the subject. So how do we go from a pile of books on the floor, to nicely organized books on the proper shelves? The answer is 2/3rds metadata, and 1/3rd taxonomy.

Metadata is data that describes data. In the case of the Dewey Decimal system, that data helped to organize books into categories such as fiction or non-fiction, and provide additional tags such as animals, psychology, religion etc. so that you could much more easily identify basic keywords that described the material. In the library system, that information is collected, identified, and then recorded when the book is first brought into the library so that the material can be properly placed as well as be identified within a cataloguing system to be more easily retrieved. Do your SharePoint libraries behave like that?

Taxonomy is the organization of metadata. In the example of the library, who determined that fiction and non-fiction should be one of the primary organizational metadata to categorize books? Why not hard cover and soft cover? Within your own organization, the determination of metadata and the taxonomy surrounding it is purely yours. It needs to reflect your organizational goals, which is why companies like Microsoft can’t exactly make that an out of the box feature. YOU have to address it, and unless you like sorting through a million books, you need to address it yesterday.

If you haven’t already addressed it, let me help you with a few tips.

Focus on process

Data is a byproduct of process. Data simply wouldn’t exist if it didn’t have somewhere to go or something to be done to it. Knowing and understanding the key processes in your organization is a must. What can be more difficult is the identification of key areas where your processes will likely change, or where you would like to change in the future. The reason we need to identify this as best as we can is so that we can better lay the ground work now. In other words, after we know what the current process is, we need to ask "What is likely to change? What additional information might be needed to identify problems or opportunities that we could leverage to further improve the process?" As an example, if we examine a simple project management site where we record change requests and have their statuses updated, could you easily identify the total amount of time it took to go from request to resolution? Could I easily identify the chain of events that happened after receiving a change request? And is either of those 2 details important to me or will be important to me in the future? Questions such as those will help take you beyond simply recording a change request and marking it as ‘resolved’. Better metadata = better taxonomy = better processes.

Have Multiple Taxonomies

Taxonomy is fairly simple in concept in that it is leveraged metadata. I think I’ve already established the importance of having some type of taxonomy. Although what I am about to say is really two versions of the same thing, for the sake of the SharePoint argument I am going to separate the taxonomies into 2 types; Navigational taxonomies and categorical taxonomies. The reason for the separation is so they can be planned according to their primary usage in that users are either finding the data they need, or working with the data to make decisions. By focusing on their usage, we can hopefully make a better taxonomy.

With navigational taxonomies our focus should be on the Use Cases that you have established for the project. By focusing on what people do with the site, we can streamline their access to their data. You won’t be able to establish that unless you understand what people do with your site, and Use Cases are the best way to establish that.

You should also support more than one navigational taxonomy since there isn’t only one way to complete a task. The goal of the menu navigation should be task focused, so how do we add a second navigational taxonomy? By adding more menus? No. In SharePoint, we can add these extra navigational taxonomies through the introduction of a Site Directory focused site, and/or through the use of custom search pages and results. Both of these options are relatively easy to implement and will allow your users a second and or third way to find a location in your growing architecture.

Categorical taxonomy can be a bit harder to implement since it deals directly with content. We need to collect metadata on content to better describe it, but what should that metadata be? How should it be best structured? Great questions and the first answer lies within understanding the various processes surrounding your data. How it will be used, what decisions need to be made on it, etc. The metadata from this is typically well understood and most organizations have little trouble in establishing what the metadata is rather they have trouble in establishing how to best implement it within SharePoint.

Let me give you some tips in establishing categorical taxonomies;

Use Content Types

Content types are a way of establishing a common structure that can be shared amongst lists and libraries. Use them if you want to establish some consistency.

Use the Managed Metadata Service (MMS)

You can think of the MMS as a place to store the common vocabulary for your organization which can be used and shared in a number of ways. Another advantage is that you can disseminate the administration of the terms to the people that use them and not IT. Be aware that the MMS interface within the Document Information Panel is only supported within Office 2010.

Support Views

Views are a great way to change to look and organization of a list or library. They work by changing the display of the data, such as sort order, which columns are shown etc. Good views require good metadata.

Support Soft Metadata

Hard metadata is metadata that directly fulfills a business requirement. In other words, it really needs to be there and usually in a very structured way where we control the terms and their usage. Soft metadata on the other hand is metadata that doesn’t have a direct business relationship but can offer some insight to the content. A good example would be in the way that we tag photos. Quite often we will need some hard metadata such as the date that the photo was taken and the location, but we want to support soft metadata so that users are able to tag the photo with open terms, such as ‘wildlife’ or ‘Christmas Party’. But why do we want to support this? To which my answer is ‘Do we really want to turn away free information?’ Granted there is a minimal support cost to this. In the end, we have content that is simply more usable, and with any luck, could be leveraged one day, so I often tout that the support costs are minimal with a potential for much gain, so why not. SharePoint 2010 can implement this many ways including using keywords, and/or open MMS term stores.

Archive

This has been a thorn in my side almost wherever I go. We work in the information age and are so-called masters of information technologies, so why are we so bad at archiving strategies? A common dialog I often have with my clients goes something like this: "Our data retrieval is slow because we have a lot of it, over a million rows.", "Why do you have over a million rows in your table?", "We need to keep our data for X years.", "Did anyone say you need to keep it in the same storage medium as the daily production data?", "Ummm, no.". Archiving data does not have to be offline, it can be online and accessible, it simply has a different purpose than your live, day to day, data, most importantly it should be separated. Every time you create a new location where users can add content, whether it be a list, or a library, or a database, or a file share, you should ask yourself "How does this content retire?" and "When does it change its purpose?" After that, automate the process. Without an archival strategy you are setup for failure, you just don’t know when. By accumulating data over time, you cause the live, day to day, data to slowly become harder to use when it is left in the same storage medium. Retrieving data will be slow, and it will often get in the way of users trying to find the correct content while they are trying to accomplish their day to day tasks.

Next week Part 2. Project management…

NeilMcIssacNeil McIsaac (MCPD, MCITP, MCTS, MCSD, MCDBA, MCSE, MCSA, MCT) is an accomplished educator, consultant, and developer who specializes in enterprise application development and integration, application architecture, and business intelligence. As an instructor, Neil shares his knowledge and years of experience with students on a wide range of topics including SharePoint, BizTalk, SQL, .NET development, and PowerShell. He recently did an interview about SharePoint in the Cloud with .NET Rocks

Neil is an owner of BlueGreen Information Technologies Inc., and has over 18 years experience working in the IT industry in both the private and public sectors. His focus on large scale application development and integration keeps Neil involved almost exclusively with enterprise level companies. However, he also works in every level of government.

Neil lives in Moncton, New Brunswick Canada. In his spare time, Neil enjoys downhill skiing, golf and a new motorcycle.

This blog is also posted on the Canadian Developer Connection

Exam Taking Tips for Certification

For many people taking an exam can be really stressful. In this blog post I’d like to see if I can take some of the fear away from taking that exam. This is the final post in my series on How to get certified. Before you take the exam you should complete the first 3 steps. Let’s be clear, I said before you TAKE the exam complete the first 3 steps. I recommend scheduling the exam as soon as you have chosen your certification goal (step 1). By scheduling your exam you commit yourself to a date and suddenly you have a target, instead of taking the exam ‘someday’ you now know exactly when you are taking the exam. Just setting a deadline makes you more likely to meet your certification goal. We have four steps to complete to earn a certification:

  1. Choose your certification goal/exam
  2. Figure out what you don’t know
  3. Fill in the gaps
  4. Take the exam

We’ve talked about how to prepare in the blog posts describing the first three steps, now it’s time to focus on the exam itself.

Scheduling the exam

You schedule your exam at a Prometric testing center. They have locations across the country. When you visit their website to schedule an exam you will be provided with a list of testing center locations to choose from. After you select a location you will see a calendar which displays the available exam times at that testing center. The website also gives you the option of phoning if you need help scheduling your exam. You will also find answers on the website to frequently asked questions such as how much does the exam cost? and What is the policy for rescheduling the exam. Keep an eye on the Microsoft Learning site for promotions that might give you a discount or a free second try of your exam if you don’t pass the first time.

What’s that? Did I say “If you don’t pass!” Yup, I think that is everyone’s greatest fear, failing the exam. Okay now think about this for a second, if, worst comes to worst, and you don’t pass. You are out the cost of the exam. You will not be the first or the last person to fail an exam. Take a deep breath, shrug your shoulders, look at your exam score sheet to check where you scored well, and where you need to study. You just completed Step 2: Figure out what you don’t know, now re-execute Step 3: fill in the gaps with some more studying, and try again.

But let’s do everything we can to help you pass the first time! You’ve scheduled your exam, you’ve researched what is on the exam, you’ve studied the topic areas to fill in the gaps of your knowledge, now it is time to walk through that door and take the exam itself.

The day of the exam

I recommend giving yourself extra time to get to the testing center. Plan on arriving 30 minutes early, that way if you do get lost or stuck in traffic you will still make it on time. If you arrive early, all the better, you can fill out the paperwork, and sit down for a few minutes reviewing a few notes before you start. Don’t forget to bring government issued Photo ID and the exam confirmation information which has your Prometric ID, Exam number, and start time.

At your appointed start time you will be asked to hand over your cell phone, and any bags such as a purse or backpack you have with you. You will be given either a pad of paper and a pen, or a plasticized piece of paper and a whiteboard marker and eraser that you can use to take notes for yourself during the exam.

You will be taken to a computer where the test administrator will make the sure the exam is loaded onto the computer and help you launch the exam. You will be presented with a series of questions you need to answer. There will be a timer (usually in the top right corner of the screen) that indicates how much time you have left. Some exams are broken into sections and you are given a fixed amount of time for each section, other exams give you a fixed amount of time to complete the entire exam. So don’t panic if you see a timer counting down 15 minutes when you are only on question one. Expect somewhere between 40-60 questions.

The questions generally follow a fairly standard format. First you are given a scenario “You are maintaining a SQL Server 2008 database on a Windows 2008 Server”, then you are given a problem statement “your project needs to store binary data and requires very fast update and retrieval capabilities” then you are asked the question “which solution best meets the needs of the team”. Watch for statements such as  which solution “best” meets the needs of the team, that will help you narrow down which answer is correct, you can use VARBINARY, or Filestream to store binary data, but which is faster? remember the question stated the team required fast update and retrieval.

You may be asked to choose one correct answer, or two correct answers that together make a correct answer, or two correct answers each of which is correct on its own. Read carefully to make sure you understand what is being asked.

When you see a question you are unsure of, you can mark the question for review. After you have answered all the questions a summary screen is displayed and you can go back and review any questions. Personally I do not go back and review every question, instead as I go through the exam, I use the Mark for review option to help me remember which questions I wanted to go back and spend more time on if I had time.

Quick tip, if you have answered a question and the Next button is disabled, the system has not crashed, the exam is designed to force you to see all the answers before you can move on to the next question, so you may have to scroll down to see the the bottom of the last answer before the Next button is enabled.

After you have answered all the questions you will be given a chance to provide feedback on the questions and the testing center. After you submit the survey you will see a screen pop-up with your score, and at that point all you hope for is that magic 700! 700 is the passing score for a Microsoft certification exam, and just to clear up a common misconception, 700 does not equal 70%! Every exam goes through a beta testing process that helps Microsoft determine a reasonable passing score, so for an easy exam you might need better than 70%, for a tough exam you might need less than 70% to pass. There is a blog post on Born To Learn that explains this in more detail.

700 may not equal 70% but in my mind 700 = 1000. What do I mean? If you look at your transcript it will simply show that you passed the exam. I have passed exams with scores varying from 700 to 980, in the end all that really matters is you passed!

I have taken many certification exams over the years, so today’s Top 5 is all about Tips to help you when you take the exam, but this week you get double for your money a Top 10!

Top 10 Exam Tips

  1. Don’t Panic! Yup, Douglas Adams had it right when he wrote HitchHikers Guide to the Galaxy. I have taken exams where I had no idea what the answers were to the first 5 questions. Don’t panic, just do your best and carry on. In the words of Captain Taggart in Galaxy Quest Never Give Up Never Surrender! Don’t give up part way through. Always finish!
  2. ANSWER EVERY QUESTION! I cannot emphasize this enough, even if you have no idea what is the right answer, guess! You do not lose points for answering incorrectly, so you may as well guess, you might get it right.
  3. Rule out wrong answers Sometimes when you aren’t sure of the answer to a question, you can look at the answers and determine that one or two of the answers are incorrect. Now your odds of guessing the right answer just went up. Sometimes incorrect answers are blatantly obvious.
  4. Spot the difference. Sometimes you have four very long answers to choose from. Instead of spending 10 minutes trying to understand the answers in detail, if you compare the answers you might discover that the only difference between the choices is one parameter. So you may not need to figure out the entire answer, if you can find the difference between the answers you can use that difference to determine which answer is correct.
  5. Mark questions you don’t know and come back to them. Sometimes you get a question later in the exam which will help you figure out the answer to an earlier question.
  6. When in doubt go with your first instinct. Your first guess is usually the right one
  7. If you have to memorize options, write them down, then just before you walk into the exam room review them one last time. You will have to throw out or give the administrator your piece of review paper. But as soon as you sit down in the exam room you can jot it down on the paper provided while it is still fresh in your mind.
  8. If you know the answer before you read the suggested answers go with it! Sometimes I read a question and my brain immediately thinks “I know what feature they want here”. You are probably right. So now just go look for the answer you thought of in the suggested answers and select it.
  9. Check the time a quarter and half way through the exam. Don’t stress yourself out by checking the time after every question, just do a quick time check at the quarter and half-way points to make sure you are on track
  10. Get a good night’s sleep. Chances are one more hour of sleep will help you more than one more hour of cramming.

If you have taken an exam, I bet you have your own exam tips to share. So tell us your tips! and GOOD LUCK ON YOUR EXAM!

This blog post is also posted to the Canadian Developer Connection

By The Way There is no documentation (yet!)

In the past few weeks I have talked about some tips on how to survive when you inherit code from someone that has no associated documentation. We looked at how to generate dependency graphs, and how to generate sequence diagrams. But sometimes we do make an effort to document our code. If you are going to spend time documenting code you want to ensure that is time well spent.

One of the problems I ran into on occasion was documentation that was created during coding could not be located by the developers down the road when they were supporting the application. As a result, I am a big believer in including code documentation within the code itself. If the documentation is part of the project and the code, then anyone who has access to the code has access to the documentation. This is why even though they have been around for a while, I love XML comments and wanted to remind you of a few tips to make them as easy as possible to work with.

To add XML comments to your project just go to the beginning of the class or method and put three “/” marks on a line then hit enter (C#) or three ‘ single quotes (VB). When you hit Enter you will get a skeleton for XML comments you can fill in

        /// <summary>
        /// 
        /// </summary>
        /// <param name="StudentToAdd"></param>
        /// <returns></returns>
        public string Add(Student StudentToAdd)
        {

The XML skeleton that is generated will be different depending on where you add the XML comments. The skeleton is just a starting point, you can add a number of other elements to your XML documentation as well by just going inside the XML comments and entering a “<” symbol the intellisense will give you a list of elements to choose from as shown in Figure 1

.csharpcode, .csharpcode pre
{
font-size: small;
color: black;
font-family: consolas, “Courier New”, courier, monospace;
background-color: #ffffff;
/*white-space: pre;*/
}
.csharpcode pre { margin: 0em; }
.csharpcode .rem { color: #008000; }
.csharpcode .kwrd { color: #0000ff; }
.csharpcode .str { color: #006080; }
.csharpcode .op { color: #0000c0; }
.csharpcode .preproc { color: #cc6633; }
.csharpcode .asp { background-color: #ffff00; }
.csharpcode .html { color: #800000; }
.csharpcode .attr { color: #ff0000; }
.csharpcode .alt
{
background-color: #f4f4f4;
width: 100%;
margin: 0em;
}
.csharpcode .lnum { color: #606060; }addingNewXMLElementZoomedin

Figure 1 Adding Additional XML Elements to the Comments

 

You probably want to sit down at the beginning of a project and decide what elements you want to include for different objects such as classes, methods and properties. After doing this you will want to standardize it for your team by modifying the default skeletons. Well good news, if you are a VB developer you can create a document called VBXMLDoc.xml, for instructions on where to find this file and how to edit it, see the MSDN article Recommended XML Tags for Documentation Comments. If you are a CSharp programmer unfortunately for now we don’t have an equivalent file, but you can create code snippets for the different skeletons.

By the time you are finished entering the comments it can start to take up a fair bit of screen space which can be annoying when you already know your way around the code.  You can collapse/expand the comments using the +/- symbols or CTRL+M CTRL+M (if like me, you prefer keyboard shortcuts) as shown in Figure 2.

CollapsedCommentsZoomedIn

Figure 2 Collapsing comments

 

So now you have comments in your code, which can be accessed by all programmers who are working on the code in the future, but honestly I can just do that with normal comments and I can use Code Snippets to insert skeletons. So why use the XML comments? there are two great reasons to use the XML comments

You can generate an XML documentation file from your XML Comments

When you build your project you can generate a file that contains the XML comments. This gives you one document which summarizes all your classes and their members that you can make available to other team members. To generate the documentation you can either specify /doc using the command line compiler or if you are building from within Visual Studio go to Project Properties | Build | Output and select XML Documentation file as shown in Figure 3

GenerateXMLDocumentationProperty

Figure 3 Setting Build Options to Generate XML Documentation File

 

Generate Help files from XML Comments

You can generate Help files from XML Comments using Sandcastle which is available on CodePlex. Sandcastle will generate Microsoft style help topics by reflecting your assemblies and reading your XML comments. Help files are an often requested by users and can be a tedious task for development teams so why not leverage XML comments to help with documenting your code and generating the help files!

So instead of creating a separate document that contains the documentation for your code, keep it with your code where the next programmer will always be able to find it, and if you are going to take the time to document your code consider getting your comments to do double duty as source information for user help!

Today’s Top 5 is of course related to documenting your code

5 Best Practices for adding comments to code

  1. Add comments at all levels – explain the purpose of the class and the methods not just the methods themselves.
  2. Tell me something I don’t know – telling me that a method called Insert will do an insert is not very helpful, what will it insert, are their parameters that affect how it will perform the insert
  3. Document the exceptions – When I call someone else’s code I really like to know what exceptions may be raised by that method, so please tell me what exceptions my code needs to handle
  4. Be professional – as tempting as it may be sometimes to write tongue in cheek comments, it’s always best to take the high road and keep your comments professional
  5. Set a standard – define what you will document for each type of object and consider also standardizing the writing style, will it be bullet point, complete sentences, third person, first person, present tense, past tense? This is particularly important if you plan to generate help files from the comments.

Visual Studio, so much more than just a code editor Smile

This blog is also available on the Canadian Solution Developer Blog

How to Get Consensus in a Meeting with the “Fist of Five”

FistHave you ever been in a meeting and asked “Is everyone okay with this plan?” only to be answered with silence. You prompt again “any concerns or questions"?” again nothing. Finally you announce that you are going to assume silence means consent and move on to the next topic. But here is the big question: Is silence consent? 

In order to answer that question, think about what happens after the meeting where you assumed silence was consent. After the meeting, did one of the team members turn to another and start pointing out the flaws in the plan? In the coming days and weeks did anyone keep bringing up that same topic again because of additional concerns? In the worst case scenarios when you go ahead with the plan and it does not work. Is there someone who stands up at the Follow Up meeting and says “I knew this plan would never work”? Those are all signs that the team did not reach a consensus.

The Merriam Webster defines consensus as “general agreement” and “group solidarity in sentiment and belief”. It’s that second definition group solidarity you want to reach with your team.  Group solidarity means we all agree to support this decision or plan going forward. That means we won’t walk out of the room and start telling everyone this is a bad idea, and we don’t think it will work. It means that even if it fails you will stand up and say you agreed it was worth trying.

Consensus is not a group vote where majority rules. It is the entire group agreeing to support a decision or idea. There is a very simple technique you can use check for consensus: The Fist of Five.

When you are ready to ask “Is everyone okay with this plan”, each team member responds by raising their fist with one to five fingers.

  • Five fingers – You think this is a very good plan and you fully support it
  • Four Fingers – You support this plan, it’s not perfect, but you strongly support it
  • Three fingers – This plan may not be your first choice, you have some concerns about it, but you understand the arguments presented in the meeting and you agree that given the current circumstances it is a reasonable plan moving forward and you support it
  • Two fingers – There is an issue you feel must be resolved before you can support the plan, further discussion or follow up is required before you can support it
  • One finger – You do not support this proposal, you do not think it will work, it is going to take some serious convincing to get you to change your mind

If everyone is showing 3 or more fingers then you have consensus. If anyone is showing less than 3 fingers ask them to explain their concern and develop a plan to address and follow up on that concern.

It’s simple, and it works. In fact we had a team meeting this week where we were putting this technique to good use as we discussed how to work with user communities, developers and IT Professionals across Canada. Besides what could be better than a meeting technique that sounds like the title of a Kung Fu movie!

All those in favour?

FistFive

This blog post also appears on the Canadian Solution Developer