Eli Robillard's World of Blog.

Bligger. Blagger. Blogger.

  • So you want to be a technical writer. . .

    Writing is a little like presenting in that many people with much to share are great at communicating informal conversations and e-mails, but have a basic fear with either presenting, or with the prospect of "technical writing." With presenting, the way forward is easy - start with a small audience like a user group or a local Toastmasters chapter and build from there. With technical writing the approach is more like learning to code - the best path forward is to get a good desk reference and start reading other people's code to see how concepts are pieced together.

    The best desk references for writing are style guides. Style guides aren't something you need to read cover to cover. Typically I flip through, read the interesting bits on language and style, and come back to the guide to look up specific pieces like citing references, labelling diagrams, terminology, and so on.

    The place to start, and the best book ever written on writing is Elements of Style.

    The Microsoft Manual of Style is a terrific guide to technical writing, though the Kindle version is to be avoided as the formatting did not translate well. The 4th edition brings it up-to-date with guidance on writing about mobile devices, SEO and other modern topics. With a little digging around the web you can turn up digital copies of the 3rd edition, which offers good advice on writing (e.g.: Ch. 3 on Globalization, or Ch. 7 on Tone and Rhetoric), though some parts are now dated (e.g.: the section on COM).

    For formal academic papers the guide to follow is the MLA Style Guide, and it looks as though there is a variant specific to "scholarly publishing" now. Also check out your local university bookstore - the U of S used to publish a great booklet that summarised the essentials for citations and formatting, and I see now they offer a nice Editorial Style Guide online with guidance for business writing.

    Not directly related, but one of the more enjoyable style guides is the Washington Post Deskbook on Style. This is the book where I first learned the hallmarks of a good obituary and why news agencies always refer to the "alleged" crime. Plus I like the writing style of the Post and found it interesting to read from where that mindset flows.

    Reference in hand, the next step is to "start reading other people's code." MSDN is awesome in its consistency and the best example of all their style guide has to offer.

    If writing for an academic audience, check out what Microsoft Research (MSR) has to offer. MSR publications are mostly written as formal papers closer to what the MLA guide prescribes, and reading a few will give you a feel for the language and layout. They're also simply great reads on topics that often turn into products in months and years ahead.

    Conclusion: If writing a whitepaper or even a book, the Microsoft Manual of Style and The Elements of Style will serve you well. If writing for a more academic audience then get the MLA guide and read a few academic papers to get a feel for the language and layout. If you have a specific publication in mind, then contact their editorial staff as many have their own guides or templates for submissions.

     

    Are they any other great resources you recommend? Sound off in the Comments!

    Read more...

  • SharePoint Conference Keynote with Bill Clinton

    Writing to you today from the mid-front of the room at Microsoft's SharePoint Conference 2014, where Bill Clinton is about to deliver the keynote. As the clock ticks the embargoes are over and reports are starting to come in on the next wave of SharePoint and Office 365. As I add to this post I'll put the interesting technical bits and links at the top and leave the inspirational parts as the closer.

    Read more...

  • How to get your SharePoint dog to hunt.

    [In response to a question on #SPYAM I wrote this update of an article form 2010 titled "The Relative Effort of SharePoint 2010 vs. 2007." -Eli.]

    SharePoint is the best demo-ware ever, and that is why it is a multi-billion dollar product. It’s like going to the pet store and seeing a great dog that does backflips all kinds of tricks – and it really is a smart dog and it does all those tricks – but when you get it home you realize that what you need is a dog that hunts. SharePoint can be trained, but is fundamentally a platform where Microsoft's first priority was first to get the foundations right - to make it trainable and extensible, and today their priority is to make it work and scale in the cloud - their cloud.

    If Microsoft's O365 scenarios are not your scenarios, then it is again time to fill the gaps with custom solutions and Apps. You need an experienced architect because solution design matters. You need to know what infrastructure you need to support your solutions. You need to know what components are out of scope for your business case so you do not provision needless infrastructure. If you want a hybrid of cloud and on-premise in any way, you need knowledge of both.

    And fundamentally, you need to understand what specific business need you are solving so an appropriate solution can be delivered to meet it. "We need SharePoint" always ends in low adoption. "We need a generic template that works for both per-client CRM and project execution" always ends in low adoption. "We need a website where we can share shedules and designs with clients to support construction projects" is a specific need that can be designed and delivered. Solutions with a concise purpose and audience are seeded to succeed.

    SharePoint is complex. There is no substitute for the knowledge and skill needed to design and deliver efficient, maintainable, and extensible solutions. If we were talking about a brand new paradigm with its own model - like when Facebook or Twitter were first released - I might agree with your executive - go ahead and kick the tires. But we're talking about your business, so unless you're okay to proceed out-of-box and without any competitive advantages, that dog will not hunt. Get some experts on your team.

    Read more...

  • How to Start a User Group

    At this year's SharePoint Conference there was an active Community Zone where people could learn more about user groups, MVPs, and current events in the SharePoint community. I answered questions in the Community Zone on Monday and the most frequent was "How do you start a User Group?" Here are my thoughts, and I'd love to hear yours so please comment.

    The first and only requirement is location, once you have one you can book a speaker and make your announcement. Find a location where you can get consistent access as often as you plan to meet (e.g. monthly).

    It helps to choose a consistent day each month (e.g. "the third Wednesday of each month") and be ready to announce your next meeting's speaker at each meeting. If you can't plan that far ahead, give members at least a week's notice. The longer notice you can give, the more people you will attract.

    Build a website. I like Meetup.com because it's free for small groups and inexpensive as you grow (~$75/year). You can host your own SharePoint site but be aware this is a significant committment that introduces risks that a volunteer-run UG doesn't always have the resources to support. Meetup.com takes that whole headache away and lets your planners focus on planning (find ours at http://www.tspug.com).

    At your first meeting (or every meeting) ask people what they want to learn about. I write the ideas on a board or flip chart and then run through the list a second time to vote on topics. For the top 3 to 5, ask if anyone there would would like to present. You can often plan 2-3 meetings at a time like this. The point is to involve people and asking them what they want their group to be is a good step towards being able to ask them to contribute.

    A box of reusable name tags goes a long way. 

    After your first meeting register the group with MSTC: https://www.technicalcommunity.com/

    A user group exists for the community of its members, not its sponsors. While all UGs rely on sponsors for facilities, speakers, giveaway items, catering and other perks, you will build a stronger community with a policy of inclusion rather than exclusion. If you ever have to ask or answer who is "allowed" to be a sponsor or speaker know that you walking a slippery slope. Diversity strengthens.

    If you have a website that collects registrations or if you collect business cards for raffles at meetings then have a privacy policy. Here's an example: http://files.meetup.com/1679846/Privacy%20Policy%202010-12-13.docx

    Your own members are your best speakers. Develop them. A night of 10-minute talks is a great way to encourage new speakers to share their stories.

    At TSPUG we start meetings by having new people introduce themselves and doing a general Q&A. People are often there to find answers, and if you can supply them right away they can sit back and relax for the rest of the night. User groups started as gatherings to talk about work. While those are officially "SharePints" now, always set aside time for people to chat and get to know each other.

    Let your local Microsoft office know you exist and ask for their support. Get your group announced in their regular missives to partners and customers (e.g. MSDN Flash), ask for giveaways, ask them to present. 

    As you grow, delegate. Different people can confirm the facility a few days ahead, coordinate speakers, check the registration count for catering, answer queries on the website, act as emcee, and tabulate evals.

    Speaking of evaluations - use them to get feedback about what people want to see, and get comments and scores to your speakers so they can improve. To encourage people to fill them out, use evals to raffle off the prizes you've collected from sponsors.

    Sit back and enjoy your new user group!

    What did I miss? Do you have a story to share? Comment!

    Read more...

  • Our Toronto Mayor

    If our ex-mayor coaches football the way he runs City Hall it probably goes something like this. . .

    Coach: All right team, this is the league final, the game we've played so hard to get to all season. Out there are provincial and national scouts with contracts in their pockets, all you need to do is take the title. Here's the gameplan: Get out there and play the best soccer of your lives.

    Player: Hey coach, no disrespect but uh, we're a football team.

    Coach: Not tonight boys. Tonight we're mavericks playing by our own rules, and soccer is just another name for football. We're going to win this title on our own terms and pity the fools who say otherwise.

    Player:  What about the refs? If we kick the ball around and don't stop play on whistles, our guys are going to get kicked off the field. How do we make any points without TDs and field goals?

    Coach: Let the other suckers read their left wing commie rule books, and see how far that gets 'em. Hah, because we'll be playing soccer! One step ahead! It's brilliant! We don't need no stinking refs. Most of those losers are dead weight and the rest are politically motivated. How can you know you're going to win if you play by the same rules as the other team? We're underdogs! Mavericks! We make points by putting the ball into the goal. Heck we'll bring our own ball, and our own goal. And dictate the rules as we go. If I couldn't do that I wouldn't be coach - I took this job on my own terms and those are them. I make the gold, I make the rules. It's not how you play the game, it's whether you win or lose in your own mind.

    -----

    Surprisingly, coach's tactics did not go over well with the pinko refs, er, judge.

    http://www.cbc.ca/news/canada/toronto/story/2012/11/25/toronto-ford-conflict-case-decision-release.html 

    Ford pledges to fight the decision "tooth and nail" rather than with "knowledge and common sense," leading inside sources to believe that his attention was simply still on lunch rather than the legal battle at hand.

    Read more...

  • Recent SharePoint 2010 Books [CanCon]

    Here in Canada, and particularly in south Ontario we're lucky to have an exceptionally strong SharePoint community. With the publication this month of Ruven Gotz's Practical SharePoint 2010 Information Architecture I count at least 6 books that were either written by, or contain contributions by our local SharePoint MVPs. Bookmark this post or watch my tweets for updates as I post reviews and add other local titles.

     

    Practical SharePoint 2010 Information Architecture by Ruven Gotz
    Not yet reviewed.

    Practical SharePoint 2010 Information Architecture

     

    Professional SharePoint 2010 Development 2nd Ed., co-authored by by Reza Alirezaei, co-technical editor Eli Robillard
    I'm a biased reviewer of this volume having contributed to the 2007 version and provided technical editing for several chapters of this release. That said, this is a great developer reference written by the experts who know these topics best. I wasn't aware of who the authors were during the editing process, and with each chapter I wondered, "was this written by the product team?" Seriously good insights, highly recommended.

    Professional SharePoint 2010 Development

     

    SharePoint 2010 Enterprise Architect's Cookbook co-authored by Reza Alirezaei
    Not yet reviewed.

    Book Cover

     

    Real World SharePoint 2010, co-authored by Reza Alirezaei
    This is a terrific collection of chapters by 22 SharePoint MVPs; basically 22 experts writing about the subject areas they live and breathe daily.

    Real World SharePoint 2010

     

    Microsoft SharePoint 2010 Development Cookbook by Ed Musters
    This book is like a self-paced introductory class in SharePoint 2010 development led step-by-step by an experienced, thoughtful, well-spoken instructor, which is exactly who Ed is. Every topic Ed covers is treated in terrific detail, and that said, my only caveat would be to check the table of contents to be sure that the topics you are interested in are covered. This is a focused, hands-on introduction to standard skills - building a development machine, columns and content types, event receivers, web parts, packaging, basic workflow, basic branding, the client object model and more. And once you absorb this one you will be ready for more advanced material.

    Microsoft SharePoint 2010 Development Cookbook

     

    Expert SharePoint 2010 Practices, co-authored by Ed Musters
    Not yet reviewed.

    Expert SharePoint 2010 Practices

     

    And one more by the Easterners: Beginning SharePoint 2010: Building Business Solutions with SharePoint co-authored by Amanda and Shane Perran
    Not yet reviewed.

    Building Business Solutions with SharePoint

     

    Thanks to all my local colleagues for taking the time to share their insights with the world-wide community. This collection represents hundreds of hours sacrificed from family, friends and work, and multiples of that in practical experience. Have I missed any? Do you have reviews of your own? Let me know in the comments.

    Read more...

  • SharePoint Summit 2012 - Thank you!

    Thanks to Danny, Reza, all the speakers and the rest of the team for hosting another great SharePoint conference in Toronto. Also a shout-out to the SharePoint Blues Band for putting on a great show Tuesday night, and for the privilege of joining them on-stage to play one of my originals. It was a lot of fun, and I hope we can do it again next year or sooner!

    Also a big thanks to everyone who attended my session on Large-scale SharePoint Architecture. I've attached the deck to this post and added some of my thoughts in the notes, so it should be a good read even if you couldn't be there in person [Download].

    Also as a special bonus I've uploaded my personal collection of Visio Shapes. I've been growing this template for several years now and use it almost daily, and I'd be interested to read or see how you use it too [Download].

     

    Further Reading:

    2012 SharePoint Summit Toronto

    @SP_Summit Twitter Feed

    Conference wrap-up message from Danny

     

    Read more...

  • Search: are you willing to manage it as an application?

    The question was asked, "how hard is it to configure FAST and what does that effort give you?" The none-too-helpful answer is that with every search product you get what you give. FAST happens to have more substance so logically there will be more to configure than some alternatives, and you can get more out of it in the long run and continuously grow its ROI as you learn its ropes.

    First ask what you're searching for - know your corpus. How large is the corpus, how many users will you have in years 1/2/3, is this a single farm or several geo-distributed farms, and is there non-SharePoint content to index (databases, public web sites, file shares, etc.)? Just as important is your organization's previous experience with search - do people wince when search is mentioned? Have you used search applicances? Do you have librarians, taxonomy managers, or a dedicated search curator? Have you customized or built apps on top of search? If what you have now brings the shivers, then it's easy to win friends and influence people just by delivering search that doesn't suck.

    And now we arrive at the central question: Are you willing to manage search as an application? Apps get attention. When they don't work, the business has no problem kicking butts until they're fixed. So when search is more helpish than helpful, why does no one fix it? Garbage in, garbage out. Search needs to be managed as an application.

    No search product is great when left with a default configuration. All are built to be improved, and along with the sexiness of the UX, this is where you will find the important differences in features. Capture that in your evaluations. FAST is better than many - it does some automatic tuning - but I would never bet a career or reputation on out-of-box FAST. No application or product does an acceptable job in the long run with a "set it and forget it" mentality. You would never treat your LoB applications this way. Nor does it work for Google.com, the Google appliances, FAST search, or SharePoint Enterprise Search. Users can scream at these products to serve better results all day (and they do), and the net effect will range from zero to nil.

    Even a part-time assignment - a half day every other week - will make a sizable difference to user satisfaction. That time is spent reading feedback (you do have a feedback link on your results page, right?), investigating the search logs to see if people are finding what they're looking for (and configuring synonyms and "Best Bets" if not), and building "canned queries" and other ways to ease the experience. This is how the nifty "metadata-based navigation" in SharePoint 2010 came to be, and I see other managed search applications serve magic in their companies year after year.

    So is FAST for you? It depends. If your corpus is under a million documents, your current offering is weak, and you can only afford minimal management, then out-of-box SharePoint Enterprise search is a great choice. If your indexing requirements are more demanding, or users more accustomed to a great experience, then FAST is a great choice to build on. If prepared to make any meaningful investment in people to manage search, start with FAST because it provides a great growth path for features and scalability. The question remains: To what extent are you willing to manage search as an application?

     

    Read more...