The vast collection of Human Knowledge can be found in books. And sometimes, it feels like I have a large percentage of that knowledge in my book cases at home. Through Borders, eBay, Amazon, and Bookmooch.com, I have many places to get new books to add to my collection of Knowledge.
Yet this Knowledge goes to waste unless the volumes get to tell their story. That is why I have set up numerous reading lists for myself, and following my policy of making goals public, I have placed the current book from each list in a sidebar with a link to this page and I will keep this list updated.
As you can see on the sidebar, I currently have four reading lists: Certification, Software Development, Classical Education, and Miscellaneous.
The Certification list contains the textbook necessary for the Certification I am currently working on. Right now, I am pursuing either the MCTS Asp.Net 3.5 or 2.0 certification. The 3.5 Certification is more current, but the books for the 2.0 are a lot cheaper on Amazon. Either Certification requires 70-536, which is the test I am currently preparing for.
My Software Development reading list contains books on Software Development but aren't directly related to my Certification training. For this list, I am currently reading Mythical Man Month.
The Classical Education list contains books recommended by the book The Well-Educated Mind: A Guide to the Classical Education You Never Had. I came across this book a couple years ago thanks to the Book Lover's Page-a-Day Calendar. This Book describes the classical method of education and how to apply it to fiction novels, histories, autobiographies, plays, and poems. For each genre, it provides a reading list. Sadly, even though I've attempted 3 times to start this list, I've only completed abort half of the first book on the list, Don Quixote.
My Miscellaneous reading list includes any other book not on the other lists. Currently, I am reading Getting Results the Agile Way. Scott Hanselman tweeted about the book and I decided to look into it. The book describes itself as a system for managing outcomes that is easily incorporated into an existing System. Since starting this book, I have certainly found this to be the case. If you are like most people and need to get more at of your day, then you need to check out this book.
Thursday, March 18, 2010
Tuesday, March 16, 2010
Technical Writing
Writing skills are a necessity in many different jobs, including Software Development. While it is one thing to be able to write code for a system, it is another to describe that change in writing. This can include the comments in the code, the check-in comments in the source control, a write-up of the fix in a bug tracking system, or a technical design. Each piece of documentation has a different use and target audience, and the first key for success is to understanding this and to write for your audience.
Inline code comments
Only developers will see your code comments. So feel free to use terms and language other developers world understand. The style, effectiveness and the format of code comments has been discussed and argued extensively. A Google search for "Comments in Code" returns a staggering 472 million results, so I will not attempt to discuss that here. But do remember that your audience can see the code themselves. Your comments will add nothing it they are simply repeating the code. What cannot always be conveyed through the code is why a particular coding method was used and the intent of the code.This is what your comments should explain when necessary.
Check-in Comments
Check-in comments are ained at other developers just like code comments. These comments should be short but informative. It should briefly describe what changed at a high level and for what defect or requirement so if another developer needs to know why a change was made they can reference the defect or requirement.
Defect Report
Defect reports will be read by other developers as well as testers, business analysts, and possibly support people. Writing for this large audience can be difficult at first, but I find the best approach is to write your response geared towards the non-technical folks first, and add more technical information in each subsequent paragraph as necessary. In this way, those who need just the basic information can get the information quickly, while other developers researching your issue at a later date will have all the logical and technical information that you have provided.
Technical Design
While college pretends to prepare yor for the real world, they never tell you quite how much of the time you will spend writing designs. I probably spend between 20 and 30 percent of my time reading or writing designs. The audience of your technical design may differ, but where I work, Developers, Business Analysts, and sometimes Testers will review designs, so the document must be accessible to all of them. Since Defect Reports and Technical Designs share the same audience, the guidelines for Defect Reports apply well to Technical Designs.
General Tips for Technical Writing
Remember that you're not writing the next great novel. Keep the language simple and use the same language or phrase to explain a task multiple times. There is no need to use a thesaurus to make each
10 Outline Document
20 Write Document
30 Revise Document
40 Goto 20
Software Development is unique in that in order to properly design it, you must first determine how to solve the problem. Once you have solved the problem in your head, you can begin to design it, but the process of designing it will reveal edge cases you didn't previously consider, and perhaps you will find places for improvement. Thus, you may find that you need to re-design your solution. The best way to write a technical design document is to follow the above process for a couple of iterations until you are comfortable with the document.
When writing for other developers, it is very useful to know the right terms. Every developer should know the name of common Design Patterns, technologies, and techniques, and using these terms in technical writing can allow the focus to remain on what is important, and not on the details of the Model/View/Controller design pattern.
Technical writing skills are a must for software developers. Unless you are working on a project by yourself, eventually you will need to tell someone else what the code does or what the code will do. However, even if you are the only developer on a project, code comments and documentation may save you if you ever forget why you wrote that dirty little hack in a method buried halfway down in the code base.
Inline code comments
Only developers will see your code comments. So feel free to use terms and language other developers world understand. The style, effectiveness and the format of code comments has been discussed and argued extensively. A Google search for "Comments in Code" returns a staggering 472 million results, so I will not attempt to discuss that here. But do remember that your audience can see the code themselves. Your comments will add nothing it they are simply repeating the code. What cannot always be conveyed through the code is why a particular coding method was used and the intent of the code.This is what your comments should explain when necessary.
Check-in Comments
Check-in comments are ained at other developers just like code comments. These comments should be short but informative. It should briefly describe what changed at a high level and for what defect or requirement so if another developer needs to know why a change was made they can reference the defect or requirement.
Defect Report
Defect reports will be read by other developers as well as testers, business analysts, and possibly support people. Writing for this large audience can be difficult at first, but I find the best approach is to write your response geared towards the non-technical folks first, and add more technical information in each subsequent paragraph as necessary. In this way, those who need just the basic information can get the information quickly, while other developers researching your issue at a later date will have all the logical and technical information that you have provided.
Technical Design
While college pretends to prepare yor for the real world, they never tell you quite how much of the time you will spend writing designs. I probably spend between 20 and 30 percent of my time reading or writing designs. The audience of your technical design may differ, but where I work, Developers, Business Analysts, and sometimes Testers will review designs, so the document must be accessible to all of them. Since Defect Reports and Technical Designs share the same audience, the guidelines for Defect Reports apply well to Technical Designs.
General Tips for Technical Writing
Remember that you're not writing the next great novel. Keep the language simple and use the same language or phrase to explain a task multiple times. There is no need to use a thesaurus to make each
10 Outline Document
20 Write Document
30 Revise Document
40 Goto 20
Software Development is unique in that in order to properly design it, you must first determine how to solve the problem. Once you have solved the problem in your head, you can begin to design it, but the process of designing it will reveal edge cases you didn't previously consider, and perhaps you will find places for improvement. Thus, you may find that you need to re-design your solution. The best way to write a technical design document is to follow the above process for a couple of iterations until you are comfortable with the document.
When writing for other developers, it is very useful to know the right terms. Every developer should know the name of common Design Patterns, technologies, and techniques, and using these terms in technical writing can allow the focus to remain on what is important, and not on the details of the Model/View/Controller design pattern.
Technical writing skills are a must for software developers. Unless you are working on a project by yourself, eventually you will need to tell someone else what the code does or what the code will do. However, even if you are the only developer on a project, code comments and documentation may save you if you ever forget why you wrote that dirty little hack in a method buried halfway down in the code base.
Thursday, March 11, 2010
Idle Hands
I'm currently reading through Getting Results, a productivity book based on desired outcomes. One of its guiding principles is to eliminate Analysis Paralysis, a condition that occurs when a person, Department, or institution becomes paralyzed while analyzing a set of alternatives. So much analysis occurs that nothing gets accomplished, whereas a great deal could have been accomplished if action was taken, even if it proved to be the wrong decision.
The new book Rework by Jason Fried and David Heinemeir Hansson of 37 Signals also espouses this idea that action is preferable to inaction. With the phrase 'Planning is Guessing' in the book, it is clear that the authors put little stock in up front planning.
From my limited experience, I have to agree that the state of doing is preferable to analyzing. About 2 years ago the development project I was on came to a screeching halt while many requirements were discussed for inclusion into the next release. For reasons I'll never fully understand management spent several months planning and debating the direction of our product, when we could have designed, developed, and tested a major release to the product.
During this time, the development team had little to do. About once a week I would ask for more work to do, but my manages rarely had anything for me. We had a few support issues to work on, and a few internal projects to work on, but I found myself with alot at free time.
As a developer on this project, my hands were tied. Due to a bad release cycle a couple years earlier, developers were not allowed to touch the code unless they had a specific requirement. We could have re-written piles of the code and done away with the behemoth 1000 and 2000 line functions, but that was not a decision the developers were allowed to make.
Anyway, it was during this fine that it formed a couple bad habits that l still have today. I began subscribing to numerous blogs, reading online technical articles, and even a couple of books during the day while waiting for work. During this time, I was exposed to Why's (Poignant) Guide to Ruby and Getting Real, both very good books from the Ruby community.
Today, I still find myself habitual Checking for new blog posts throughout the day, even though I have plenty of work to do. It is even worse now then before, because I'm following many more blogs today then ever.
In addition to the wasted time by having a development team do nothing for a long period of time, one also risks them becoming lethargic and the possibility that they develop bad habits that do not easily disappear when work returns.
The new book Rework by Jason Fried and David Heinemeir Hansson of 37 Signals also espouses this idea that action is preferable to inaction. With the phrase 'Planning is Guessing' in the book, it is clear that the authors put little stock in up front planning.
From my limited experience, I have to agree that the state of doing is preferable to analyzing. About 2 years ago the development project I was on came to a screeching halt while many requirements were discussed for inclusion into the next release. For reasons I'll never fully understand management spent several months planning and debating the direction of our product, when we could have designed, developed, and tested a major release to the product.
During this time, the development team had little to do. About once a week I would ask for more work to do, but my manages rarely had anything for me. We had a few support issues to work on, and a few internal projects to work on, but I found myself with alot at free time.
As a developer on this project, my hands were tied. Due to a bad release cycle a couple years earlier, developers were not allowed to touch the code unless they had a specific requirement. We could have re-written piles of the code and done away with the behemoth 1000 and 2000 line functions, but that was not a decision the developers were allowed to make.
Anyway, it was during this fine that it formed a couple bad habits that l still have today. I began subscribing to numerous blogs, reading online technical articles, and even a couple of books during the day while waiting for work. During this time, I was exposed to Why's (Poignant) Guide to Ruby and Getting Real, both very good books from the Ruby community.
Today, I still find myself habitual Checking for new blog posts throughout the day, even though I have plenty of work to do. It is even worse now then before, because I'm following many more blogs today then ever.
In addition to the wasted time by having a development team do nothing for a long period of time, one also risks them becoming lethargic and the possibility that they develop bad habits that do not easily disappear when work returns.
Subscribe to:
Posts (Atom)