I just found out that if you register for 3 sessions, you get a free copy of Visual Studio 2005 Standard Edition! Now you have no excuse not to use this link ASP.NET Developer WebCasts and help me win a prize for signing up attendees!
I will be presenting four sessions as part of the ASP.NET Developer WebCast series. My sessions present ASP.NET 2.0 and the .NET Framework 2.0 specifically for Java developers who want to learn about ASP.NET. I've had a long history of working with both the Java and ASP.NET communities and all the various issues of knowledge transfer, code migration and cross-platform development. My four sessions are:
- March 6th (10-11am pacific time) - Introduction to ASP.NET for JSP Developers Part 1 - Welcome to ASP.NET
- March 6th (1-2 pm pacific time) - Introduction to ASP.NET for JSP Developers Part 2 - Building Applications
- March 7th (10-11 am pacific time) - Introduction to ASP.NET for JSP Developers Part 3 - Architecture Deep Dive
- March 8th (10-11 am pacific time) - Introduction to ASP.NET for JSP Developers Part 4 - Migrating to ASP.NET
The first two sessions cover the basic building blocks of ASP.NET by mapping them to concepts and code that any Java web developer will be familiar with. The third session goes into much deeper detail on how ASP.NET works from the inside and how you can extend and expand this functionality in ways that are very different from Java. The final session covers a wide range of options for interoperation between ASP.NET and Java, as well as migrating code from Java to ASP.NET. Come join the fun and ask me questions about Java and ASP.NET 2.0.
If you are interested in seeing the webcast, please register for ASP.NET Developer WebCasts using this link. If you use my link, I can win free stuff!
I'm currently developing a training course for new developers who are fresh out of college. The course is a crash course in all the things you should have learned about development, but didn't. In addition to modules on enterprise coding (source control, build tools, unit testing, logging, etc), the course has a module on documentation and writing. Having far too much experience trying to read through bad writing, useless documentation and uninformative user guides, I figure I ought to share some simple pointers.
What to Ask
Before you write anything, you need to ask three questions:
- What is the purpose of the document?
- Who is the intended audience?
- What is the lifespan of the document?
As a developer, you might get asked to write a technical specification, help files for an application, API documentation, user test cases, architecture diagrams, technical white papers, training material and sometimes even sales or marketing collateral. Each type of document serves a different purpose. Know what you are trying to do before you start.
Think about your intendend audience. Different people understand technology in different ways. Is the person reading the article a tech savvy devleoper, or a high school teacher who may not think that "click the preview button" means "Move your mouse pointer over the preview button and then press the left button on your mouse." Just as you would build use cases for your code, you want to think about use cases for your writing.
Finally, you need to know how long a document is going to live. A one off tech spec might only last for the 3 weeks between signing off on starting the project and your first architecture session. A white paper might live online for 3 months or 3 years depending on how fast the technology ages. End user documentation on an application may never go away. If your writing is going to have a long lifespan, you have to make sure it is going to stand the test of time. You might also want to consider scoping in time for updating or maintaining the documentation. I've updated a set of ASP.NET 2.0 white papers 3 times based on changes from Beta 1 to Beta 2 to RTM. I've also seen API documentation that is version 1.0 when the code is version 4.0.
Once you've talked through those three questions, the next steps are to answer these three questions:
- Who needs to participate in developing the document?
- How should the document be structured?
- What writing style should be used?
If you are a nose-down developer and you have been asked to write a white paper for high school teachers, you probably want to bring other people into the writing team. At the least, you need to find yourself a few members of the target audience to act as your readers. You probably won't have the same set of assumptions as your target audience. If you try to write it on your own, you are likely to create a document that isn't going to make sense to your readers. Similarly, if you are a senior architect and you have been asked to write API documentation for other developers to add on to your system (in six months), you might want to talk to your current developers to figure out whether your original API design stood the test of development.
Different types of documents require a different structure. If you are writing an API, think about whether you want it to look like Java's Documentation, or MSDN, or something different. If you are writing user help, you are writing small statements embedded in your application and/or building a simple web site. You want to chunk up the help into many small sections that answer direct questions or have direct relevance to the function/feature you are trying to describe. If you are writing a functional specification, you need to be very explicit about defining feature sets. A large part of your documentation should be item by item descriptions. However, don't forget to provide the executive summary at the beginning to get your readers oriented to the bigger picture.
Style is the tricky part. You should always try to write in a "professional" style. In my view that means you need to:
- Avoid passive voice. I can write another six pages of blog on this issue alone.
- Use short sentences. Long sentences are great for high literature. However, they are complicated, confusing and hard to read in technical writing.
- Write in a structured fashion. Use headers. Use lists. Use pictures. The more visual cues you can give your readers about where they are and what they are reading, the better.
- Define your jargon. Don't ever assume that your audience is going to understand all of the terms you think they should know. Expand all acronyms the first time you use the term (just to prove you can!). Add an extra sentence, or even an extra section, defining business and technology terms. You may think your audience already knows what you are talking about, but adding a definition makes sure. You may also be surprised at who ends up reading your document.
Beyond these simple starting points, adjust your style for the type of document and the target audience. Sometimes, using a first person point of view (I, we) makes sense. "In this example, I will show you how to write." In some cases, such as user guides, you need second person (you). "You should click on the Preview button.". However, in most technical writing, you probably want third person, where you don't use "I", "We", "You", etc. Similarly, in an architectural document, you want certian types of pictures (UML diagrams, use cases, sequence diagrams) that would be totally inappropriate for marketing information.
Time to Start Writing
Once you've figured out who you are writing for, how you want to structure the document, and what style is appropriate, it's time to start writing. I'll blog about that some other time.
At Infusion, we're busily growing our support team. I've had several discussions recently with the team members about the mindset required to not just survive a stint in technical support, but thrive in it. Most developers freak out if they are asked to perform technical support. At best, you can expect 3 months before the complaints start, and 6 months before they are burned out and desperately want off the project. So what kind of person is actually suited for a long term role in technical support? In my experience, you need three things (in order of importance):
- Infinite patience - As a support engineer, you are part of a service organization. You deal directly with customers at their worst. No one ever calls support if things are going well and they are happy. You start in a hole in any customer relationship and the best you can do is fill the hole. Take each issue as it comes and remember that support is not personal. That's the first thing a typical developer trips on when asked to do support. The customer complains about feature X not doing what they expect, so the developer decides that either the customer is too stupid to use the product, or that the customer is attacking the developer's skills/knowledge/experience. Put some mental distance between you and the thing you are supporting. Be very patient with each customer. Your job is to make them feel better and you can't do that if you are defensive, upset, feeling attacked or otherwise emotionally invested in proving the customer wrong.
- Obsessive-compulsive behavior - Technical support is all about details. Who did you talk to about what? Do you need to follow up? Are you expecting them to follow up? If so, when? Did you log your time to the right account? The stereotypical developer chafes at rules and paperwork. The ideal support engineer keeps track of everything. If you lose a customer contact, or forget to follow up on a call, you are digging a bigger hole. If you have everything tracked and logged, you can often blow away a customer by prompting them for replies and being "proactive" on issues. Customer satisfaction with regards to support is about the impression of responsiveness. One dropped call, and you blow away all your good will. On the other hand, if you are obsessive about logging issues and following up, you build up a pretty big buffer with customers who expect you to catch them when they forget things. A really good memory is also very desirable, but you can fake it with obsessive note taking and good systems.
- Attention deficit disorder - The third property of a good support engineer is an insatiable curiosity combined with an ability to multi-task. Support is never about scheduling or planning. It's about making the most of the immediate opportunity and filling the down time with your own initiative. Our stereotypical developer wants one project to focus on, with scheduled milestones and target dates. He doesn't want to be bothered with distractions or other projects. A good support engineer, on the other hand, always has a stack of "side work" waiting for that variable time between support calls. The developer needs hours, days or weeks to refocus on a new project. The support engineer needs seconds or minutes to rememeber where they left off on a call, or shift gears to an entirely new project. Once again, note taking and good memory definitely come into play here.
So why do so many devlopers start in support, and what should they be learning from it? The answer is that support is a classic entry level position. You don't need experience (you get that daily on the job). You don't need extensive education (again, you pick up a lot of coding on the job). You aren't at risk for blowing a million dollar project (as long as you keep records, you can pass a call on to someone who can answer it). All you really need is a good attitude, some basic aptitude, and a good system to support you when you get into trouble. The best part (in my view) is that your typical young developer comes into support and has a unique chance to show whether he or she is going to become:
- A stereotypical developer - The developer hates support and wants on to "bigger projects that are more challenging" in 3 months or less. This sort of developer may become a great guru of a technology, but he or she may also be "that guy who sits in the cube and gets his work done, but don't let him talk to customers". A support engineer on this role often finds one particular aspect of the support system/product or technology and becomes the one and only expert. As a classic developer, you can let your ego surpress your patience. Don't get me wrong, being "just a developer" isn't a bad career path at all. Without the classic developers executing on deals, and building products, the rest of us wouldn't have anything to support. However, if you let yourself be "just a devloper" then you will be stuck in that role. To grow, you will eventually need the lessons you could have learned working technical support.
- A pre-sales/sales god - Sales and technical pre-sales work requires almost exactly the same attributes as technical support. The biggest obvious difference is that sales travels a lot more. Someone who thrives on the challenges of support, but doesn't want to go the hard core technical route, will often do very well in a sales or pre-sales organization. Instead of handling the back end of a project, you take on the very front end. You are still simultaneously dealing with a large number of clients, obsessively tracking relationships and leads, and have to have an encyclopedic knowledge of many different subjects in order to open up the opportunities with a customer. You are also out of the deal as soon as the ink dries. It's very much like support, only with more travel, and the occasional steak dinner with a client.
- An architect/business analyst/team lead - For those less interested in direct sales and more interested in knowing everything about everything, support is a launching pad to a role as an architect, business analyst or team lead. Support gives you the freedom and opportunity to be endlessly curious. You have to learn about every part of the supported system, from the front end to the back. You have to learn how users use the system (which is often very different than what the dev team thinks the system is useful for). You have to manage your own time, and a large number of customers. You have to juggle priorities on a daily basis. All of these things are basic training for the hard to fill roles necessary for making any development team a success. Anyone can learn to code. Not many people can learn how to translate what the user says/thinks/sees into what the developer needs to hear (and vice versa).
Support is a launching pad, not a permanent home. Put anyone on my support team for a few months, and I'll map out a likely career path for them. I don't know any other type of technology work that combines the pressures, opportunities and experiences found in front line technical support. For the very few with the mindset and skillset, technical support is an incredibly fascinating area of work. For everyone else, it's a great way to learn some of life's harder lessons!
Hello to the webverse. My world encompases a very wide range of projects. In this blog, you may read about my thoughts on:
- MapPoint Web Service (.NET, Java, PHP, Perl, and/or ColdFusion).
- MapPoint Location Service
- Virtual Earth
- ASP.NET 2.0
- Technical Writing
- Technical Support
- MSN adCenter and MSN Search
Never having blogged before, I can't tell you how often I'll post, or what will be in the next post. I can say that I'll do my best to keep the posts informative and useful.