tag:blogger.com,1999:blog-75207382024-03-09T02:43:47.633+05:30Adaptive Software SolutionsWrite Awesome User Manuals and Tutorials for Software ProductsParaghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.comBlogger251125tag:blogger.com,1999:blog-7520738.post-50039488346705439592018-06-07T21:42:00.002+05:302018-06-13T17:56:15.237+05:30Planning a User Guide - Part 4/5 - Get Your Toolbox Together<div dir="ltr" style="text-align: left;" trbidi="on">
<div style="text-align: left;">
<br />
<table align="center" cellpadding="0" cellspacing="0" class="tr-caption-container" style="margin-left: auto; margin-right: auto; text-align: center;"><tbody>
<tr><td style="text-align: center;"><a href="https://1.bp.blogspot.com/-LWb_m2QwXqk/WxlY18veSKI/AAAAAAAAAwk/GbUusicBcnE6Gp8OWZU-d5n-SChFAlH1wCLcBGAs/s1600/fleur-treurniet-325960-unsplash.jpg" imageanchor="1" style="margin-left: auto; margin-right: auto;"><img border="0" data-original-height="1067" data-original-width="1600" height="425" src="https://1.bp.blogspot.com/-LWb_m2QwXqk/WxlY18veSKI/AAAAAAAAAwk/GbUusicBcnE6Gp8OWZU-d5n-SChFAlH1wCLcBGAs/s640/fleur-treurniet-325960-unsplash.jpg" width="640" /></a></td></tr>
<tr><td class="tr-caption" style="text-align: center;">Photo by <a href="https://unsplash.com/photos/dQf7RZhMOJU?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" style="background-color: whitesmoke; box-sizing: border-box; color: #999999; font-family: -apple-system, BlinkMacSystemFont, "San Francisco", "Helvetica Neue", Helvetica, Ubuntu, Roboto, Noto, "Segoe UI", Arial, sans-serif; font-size: 14px; text-align: start; transition: color 0.2s ease-in-out, opacity 0.2s ease-in-out; white-space: nowrap;">Fleur Treurniet</a><span style="background-color: whitesmoke; color: #111111; font-family: , "blinkmacsystemfont" , "san francisco" , "helvetica neue" , "helvetica" , "ubuntu" , "roboto" , "noto" , "segoe ui" , "arial" , sans-serif; font-size: 14px; white-space: nowrap;"> on </span><a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" style="background-color: whitesmoke; box-sizing: border-box; color: #999999; font-family: -apple-system, BlinkMacSystemFont, "San Francisco", "Helvetica Neue", Helvetica, Ubuntu, Roboto, Noto, "Segoe UI", Arial, sans-serif; font-size: 14px; text-align: start; transition: color 0.2s ease-in-out, opacity 0.2s ease-in-out; white-space: nowrap;">Unsplash</a></td></tr>
</tbody></table>
<br />
<br />
In the <a href="http://www.adaptivesoftware.biz/2018/06/planning-user-guide-part-35-co-ordinate.html" target="_blank">previous post</a>, I had discussed how to organize the team for creating your software's user manual. With the team ready, the next step is to select the tools.<br />
<br />
Working with the right technical writing tools is as important in technical writing as it is in building software. The right tools will help you be more organized, productive, and accurate in your work. </div>
<div style="text-align: left;">
<br />
In software, we use an IDEs, testing tools, and version control tools to manage our work. In technical writing, at a bare minimum, we use a content authoring tool, an automated grammar checker, and visual tools to assist us in our work. </div>
<div style="text-align: left;">
<br />
I'll discuss various tools that are available in the market, link to comparisons, and share my opinion to help you make the right choice.<br />
<br /></div>
<h2 style="text-align: left;">
Help Authoring Tools</h2>
<div>
A Help Authoring Tool (HAT) offers several features that go beyond simple word processing software for writing technical documents. HATs support publishing the content in multiple formats, responsive design for different devices, indexing, single-sourcing, and context-sensitive features. </div>
<div>
<br /></div>
<div>
Here are a few popular Help Authoring Tools:</div>
<div>
<ol style="text-align: left;">
<li><a href="https://www.adobe.com/products/robohelp.html" target="_blank">Adobe RoboHelp</a></li>
<li><a href="https://www.author-it.com/" target="_blank">Author-it</a></li>
<li><a href="https://www.doctohelp.com/" target="_blank">ComponentOne Doc-To-Help</a></li>
<li><a href="https://www.helpandmanual.com/" target="_blank">EC Software Help and Manual</a></li>
<li><a href="https://www.madcapsoftware.com/products/flare/" target="_blank">MadCap Flare</a></li>
<li><a href="https://www.drexplain.com/" target="_blank">Dr. Explain</a></li>
</ol>
<div>
Even though HATs are useful, I have yet to come across a small/mid-sized software company that uses them. It's because, at most small companies, it is the developers who write the first version of their technical manual. Using a HAT cuts on two sides: first the company has to pay a rather steep fee for using the HAT, and second, the developers will have to invest time in learning the software. Both money and time are at a premium in small organizations and their requirements are usually sufficiently fulfilled by MS Word or Google Docs.<br />
<br />
It doesn't mean that HATs are not useful. If you feel that the features that a HAT offers will add significant value to your product, then I recommend that you read through the posts I have linked below to get an understanding of how they compare before making a purchase decision.</div>
<div>
<ol style="text-align: left;">
<li><a href="https://www.g2crowd.com/categories/help-authoring-tool-hat" target="_blank">User reviews of popular Help Authoring Tools</a></li>
<li><a href="https://ffeathers.wordpress.com/2010/05/30/aodc-day-3-help-authoring-tool-comparison/" target="_blank">Comparison of Help Authoring Tools - notes from a tech conference</a></li>
<li><a href="http://wouter.tech/blog/choosing-a-documentation-tool/" target="_blank">Choosing a documentation tool</a></li>
<li><a href="https://www.indoition.com/online-help-authoring-tools-survey.htm" target="_blank">A fairly comprehensive market overview of Help Authoring Tools</a></li>
</ol>
</div>
</div>
<h2 style="text-align: left;">
<span style="font-weight: normal;"><br /></span></h2>
<h2 style="text-align: left;">
Automated Grammar Checker</h2>
<div>
<span style="font-weight: normal;">An automated grammar checker is an invaluable tool for all writers. There are several automated grammar checkers on the market. Most have a freemium model where the free version at the very least corrects punctuation errors and basic grammatical mistakes and the paid version corrects more advanced grammatical issues and other issues related to sentence construction, readability, and plagiarism. Some software will also help you enhance your vocabulary - which is super awesome.</span></div>
<div>
<span style="font-weight: normal;"><br /></span></div>
<div>
I personally use the free editions of both Grammarly and ProWritingAid.</div>
<div>
<br /></div>
<div>
Grammarly is great at detecting punctuation and basic grammatical mistakes. Also, Grammarly's free Chrome plugin totally rocks. It's a huge help when I compose emails in the browser or when I write blog posts. The only downside is that the plugin does not support Google Docs. </div>
<div>
<br /></div>
<div>
ProWritingAid's free version which runs on a web interface is very intuitive and easy to use. It gives a great summary of the analyzed text, offers readability checks, checks for cliches, overused words, and several other features. Unfortunately, they include the browser plugin only in the paid version.</div>
<div>
<br /></div>
<div>
I suggest that you begin with the free versions of <a href="https://prowritingaid.com/" target="_blank">ProWritingAid</a> and <a href="http://grammarly.com/" target="_blank">Grammarly</a>. They may be all you need for working on a technical manual. </div>
<h2 style="text-align: left;">
<span style="font-weight: normal;"><br /></span></h2>
<h2 style="text-align: left;">
Visual Tools</h2>
<div>
<span style="font-weight: normal;">From the perspective of writing software user manuals, the most important visual tools are screen capturing software (to capture screenshots) and image editing software (to do minor edits to the screenshots). </span></div>
<div>
<span style="font-weight: normal;"><br /></span></div>
<div>
There are many free as well as paid screen capturing software available on the market. Here's a list of <a href="https://www.softwaretestinghelp.com/best-screen-capture-software/" target="_blank">ten best screen capture software for 2018</a>. I personally use the free version of <a href="https://www.techsmith.com/jing-tool.html" target="_blank">Jing</a> and am very happy with it.</div>
<div>
<br /></div>
<div>
Once you have the screenshots, you might want to do minor edits to highlight certain parts of the screen. Jing (and other screen capture software as well) will allow you to make highlights, circles, etc, but I don't like the quality much. I prefer to use a proper image editor. </div>
<div>
<br /></div>
<div>
Online image editors work best since they do not require installation and some even have team features. Here's a list of great <a href="https://thenextweb.com/creativity/2014/02/24/9-browser-based-photo-editing-tools/" target="_blank">online image editors</a>.</div>
</div>
Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-28400312005628452832018-06-02T23:00:00.003+05:302018-06-02T23:04:17.730+05:30Planning a User Guide - Part 3/5 - Co-ordinate the Team<div dir="ltr" style="text-align: left;" trbidi="on">
<div class="separator" style="clear: both; text-align: center;">
<a href="https://2.bp.blogspot.com/-vP8xnQmgon0/WxLUHir1ojI/AAAAAAAAAwU/de1QSIaCMIwthSP1kvxJn5-vu0hNWdxQACLcBGAs/s1600/helloquence-61189-unsplash.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="1068" data-original-width="1600" height="426" src="https://2.bp.blogspot.com/-vP8xnQmgon0/WxLUHir1ojI/AAAAAAAAAwU/de1QSIaCMIwthSP1kvxJn5-vu0hNWdxQACLcBGAs/s640/helloquence-61189-unsplash.jpg" width="640" /></a></div>
<div style="text-align: center;">
<i><span style="background-color: whitesmoke; color: #111111; font-family: , "blinkmacsystemfont" , "san francisco" , "helvetica neue" , "helvetica" , "ubuntu" , "roboto" , "noto" , "segoe ui" , "arial" , sans-serif; font-size: 14px; white-space: nowrap;">Photo by </span><a href="https://unsplash.com/photos/5fNmWej4tAA?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" style="background-color: whitesmoke; box-sizing: border-box; color: #999999; font-family: -apple-system, BlinkMacSystemFont, "San Francisco", "Helvetica Neue", Helvetica, Ubuntu, Roboto, Noto, "Segoe UI", Arial, sans-serif; font-size: 14px; transition: color 0.2s ease-in-out, opacity 0.2s ease-in-out; white-space: nowrap;">Helloquence</a><span style="background-color: whitesmoke; color: #111111; font-family: , "blinkmacsystemfont" , "san francisco" , "helvetica neue" , "helvetica" , "ubuntu" , "roboto" , "noto" , "segoe ui" , "arial" , sans-serif; font-size: 14px; white-space: nowrap;"> on </span><a href="https://unsplash.com/search/photos/team?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" style="background-color: whitesmoke; box-sizing: border-box; color: #999999; font-family: -apple-system, BlinkMacSystemFont, "San Francisco", "Helvetica Neue", Helvetica, Ubuntu, Roboto, Noto, "Segoe UI", Arial, sans-serif; font-size: 14px; transition: color 0.2s ease-in-out, opacity 0.2s ease-in-out; white-space: nowrap;">Unsplash</a></i></div>
<br />
This is the third post in a series of five posts on how to plan a user guide. In the <a href="http://www.adaptivesoftware.biz/2018/02/planning-user-guide-part-18-audience.html" target="_blank">first post</a>, I wrote about how to conduct an audience analysis and the <a href="http://www.adaptivesoftware.biz/2018/03/planning-user-guide-part-28-determining.html" target="_blank">second post</a> discussed how to define the overall scope of the manual. Once the overall scope of the user guide is defined, the next step is to coordinate the team that will work on creating the manual.<br />
<br />
A typical team will consist of the following roles. Many of these roles will be fulfilled by freelancers since they are one-off or intermittent work engagements. At the end of the article, I have provided a list of websites where you can find good freelancers.<br />
<br />
<h3 style="text-align: left;">
Creative Artist</h3>
<div>
You'll need to work with a creative artist to design the cover page and any other images for the user guide. Most small to mid-sized companies don't have a dedicated creative artist on their rolls. But that's not a problem. There are several freelancing websites where you can work with great creative artists on a gig basis.</div>
<h3 style="text-align: left;">
Photographer</h3>
<div>
If your software interfaces with machinery or other equipment, then you'll need a good photographer to shoot images of the machinery to include in the user manual. Your local yellow pages or a web search will help you locate a good photographer.</div>
<h3 style="text-align: left;">
Legal Expert</h3>
<div>
A legal expert can help you with the disclaimers and legal notices section of the user guide. For regular software products, you might be able to use free templates from the internet, but if your product caters to an industry that has government regulations in place, then it's best to seek professional help from someone who can guide you in creating appropriate terms of use, disclaimers, warnings, and other legal notices. Freelance websites are good places to find skilled legal experts.</div>
<h3 style="text-align: left;">
Technical Writer</h3>
<div>
The technical writer is the person who will understand the software from the development team and write the actual user manual. A good technical writer should have the following skills:</div>
<div>
<ol style="text-align: left;">
<li>Ability to write clearly and correctly. </li>
<li>Expertise in working with word processing software.</li>
<li>Ability to express ideas through images.</li>
<li>Ability to understand software functionality.</li>
<li>Ability to create good instructional content. </li>
</ol>
<div>
Large organizations usually have a full-time team of technical writers but most small to mid-sized companies don't have dedicated technical writers. However, lots of people work as freelance technical writers. You can connect with good them on any of the freelance websites listed later in this article. If you need to work with someone local, a web search should help you locate them.<br />
<br />
Depending on the volume of work, you may need to work with one or more technical writers simultaneously. </div>
</div>
<h3 style="text-align: left;">
Point of Contact in the Development Team</h3>
<div>
It's a good idea to assign a dedicated person from the development team who will coordinate with the technical writer(s). Such a person will have the following responsibilities:</div>
<div>
<ol style="text-align: left;">
<li>Explain the software's functionality to the technical writer(s).</li>
<li>Provide technical details such as installation requirements, FAQs, troubleshooting instructions, etc.</li>
<li>Furnish screenshots.</li>
<li>Verify the user guide for overall technical correctness.</li>
<li>Coordinate with someone who can test the user guide (explained in the next section).</li>
</ol>
</div>
<h3 style="text-align: left;">
User Guide Tester</h3>
<div>
A user guide should be thoroughly tested to ensure that all instructions produce the desired results. For example. the user guide tester should install the software on a fresh machine by exactly following the instructions outlined in the guide and verify if the software is indeed installed properly. Similarly, the tester should test all the admin as well as user features by following instructions in the user guide and verify that they produce the desired results. </div>
<div>
<br /></div>
<div>
After the testing session, the tester should produce a list of features that did not work as explained in the instructions. They should also make a note of instructions that were difficult to understand or follow.</div>
<div>
<br /></div>
<div>
You might be tempted to assign this work to someone from the software development or testing team, but I will recommend working with a person who has no prior knowledge of the software. It will cost you a little additional money and time but these will be well spent. A person who comes with a blank slate is more likely to point out mistakes that a developer or tester who is already familiar with your software will miss out.</div>
<div>
<br /></div>
<div>
You can work with freelancers or college interns to test the user guide.</div>
<h3 style="text-align: left;">
Proofreader/Editor</h3>
<div>
A proof-reader corrects superficial errors in spelling, grammar, punctuation, formatting, verb tenses, etc. </div>
<div>
<br /></div>
<div>
<div>
An editor reviews and improves how information is presented and structured. An editor will ensure that your user guide is well organized and easy to understand for the audience. </div>
</div>
<div>
<br /></div>
<div>
It's a good idea to work with just one person who will proofread and edit your user guide. </div>
<div>
<br /></div>
<div>
If you don't wish to have your user manual reviewed, then you may want to use an automated grammar correcting software such a <a href="https://www.grammarly.com/" target="_blank">Grammarly</a> or one of its alternatives to ensure that the document is grammatically correct. I personally use Grammarly for my work and I've been very satisfied with its quality.</div>
<div>
<br /></div>
<h3 style="text-align: left;">
Resources</h3>
<div style="text-align: left;">
Here's a list of websites where you can connect with freelancers:</div>
<div>
<ol style="text-align: left;">
<li><a href="http://fiverr.com/">fiverr.com</a> - a great website for finding a wide variety of freelancers</li>
<li><a href="http://freelancer.com/">freelancer.com</a> - another great website for finding a wide variety of freelancers</li>
<li><a href="http://upwork.com/">upwork.com</a> - yet another great website for finding a wide variety of freelancers</li>
<li><a href="http://99designs.com/">99designs.com</a> - A great community for finding freelancers to do logo, image, and brand design work, here</li>
</ol>
</div>
<div>
<br /></div>
<br />
<br /></div>
Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-57023317245981427572018-03-19T11:23:00.000+05:302018-06-02T11:28:43.373+05:30Planning a User Guide - Part 2/5 - Determining the Overall Scope<div dir="ltr" style="text-align: left;" trbidi="on">
<div dir="ltr" style="line-height: 1.38; margin-bottom: 0pt; margin-top: 0pt;">
<div style="text-align: justify;">
<div class="separator" style="clear: both; text-align: center;">
<a href="https://1.bp.blogspot.com/-Oj6lHFSIkns/Wq9QGfpwY2I/AAAAAAAAArE/33ZWNm2Iowck5aHyePLgK5enLwvRdZ4BgCLcBGAs/s1600/nordwood-themes-478713-unsplash.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="1067" data-original-width="1600" height="426" src="https://1.bp.blogspot.com/-Oj6lHFSIkns/Wq9QGfpwY2I/AAAAAAAAArE/33ZWNm2Iowck5aHyePLgK5enLwvRdZ4BgCLcBGAs/s640/nordwood-themes-478713-unsplash.jpg" width="640" /></a></div>
<div class="separator" style="clear: both; text-align: center;">
<span style="background-color: whitesmoke; color: #111111; font-family: , "blinkmacsystemfont" , "san francisco" , "helvetica neue" , "helvetica" , "ubuntu" , "roboto" , "noto" , "segoe ui" , "arial" , sans-serif; font-size: 14px; white-space: nowrap;">Photo by </span><a href="https://unsplash.com/photos/wt4gUtdv1-U?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" style="background-color: whitesmoke; box-sizing: border-box; color: #999999; font-family: -apple-system, BlinkMacSystemFont, "San Francisco", "Helvetica Neue", Helvetica, Ubuntu, Roboto, Noto, "Segoe UI", Arial, sans-serif; font-size: 14px; text-align: start; transition: color 0.2s ease-in-out, opacity 0.2s ease-in-out; white-space: nowrap;">NordWood Themes</a><span style="background-color: whitesmoke; color: #111111; font-family: , "blinkmacsystemfont" , "san francisco" , "helvetica neue" , "helvetica" , "ubuntu" , "roboto" , "noto" , "segoe ui" , "arial" , sans-serif; font-size: 14px; white-space: nowrap;"> on </span><a href="https://unsplash.com/collections/430077/workspaces?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText" style="background-color: whitesmoke; box-sizing: border-box; color: #999999; font-family: -apple-system, BlinkMacSystemFont, "San Francisco", "Helvetica Neue", Helvetica, Ubuntu, Roboto, Noto, "Segoe UI", Arial, sans-serif; font-size: 14px; text-align: start; transition: color 0.2s ease-in-out, opacity 0.2s ease-in-out; white-space: nowrap;">Unsplash</a></div>
<span style="font-family: "arial"; font-size: 11pt; white-space: pre-wrap;"><br /></span> <span style="font-family: "arial"; font-size: 11pt; white-space: pre-wrap;"><br /></span> <span style="font-family: "arial"; font-size: 11pt; white-space: pre-wrap;">In the <a href="http://www.adaptivesoftware.biz/2018/02/planning-user-guide-part-18-audience.html" target="_blank">previous post</a>, I described how to do an audience analysis for a user guide. Understanding the audience will help you make design decisions that will serve your users in a better way. Once you have understood what the audience needs, the next step -- and the topic of this post -- is to plan the overall scope of the manual. </span></div>
</div>
<div dir="ltr" style="line-height: 1.38; margin-bottom: 0pt; margin-top: 0pt;">
<div style="text-align: justify;">
<br /></div>
</div>
<div dir="ltr" style="line-height: 1.38; margin-bottom: 0pt; margin-top: 0pt;">
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">I have outlined below, a list of sections that most manuals consist of. It's a comprehensive list and it's quite possible that your manual won't need all these sections. This post will also help you decide which sections you need. </span></span></div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;"> </span></span><span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;"> </span></div>
<h3 style="text-align: justify;">
<span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;">Cover Page</span></h3>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;">The Cover Page contains the following details:</span></div>
</div>
<div>
<ul style="text-align: left;">
<li style="text-align: justify;">The title of the user guide.</li>
<li style="text-align: justify;">A company logo.</li>
<li style="text-align: justify;">The version number of the product. </li>
</ul>
</div>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;">Optionally, the Cover Page can also mention the publish date and a one-line copyright notice. Sometimes, these details are mentioned on the page immediately following the cover page.</span></div>
</div>
<h3 style="text-align: justify;">
<span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;"><br /></span></h3>
<h3 style="text-align: justify;">
<span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;">Legal Notices</span></h3>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;">The Legal Notices section may extend over several pages. This section begins with your company contact details which typically contain the following:</span></div>
</div>
<div>
<ul style="text-align: left;">
<li style="text-align: justify;">Corporate address.</li>
<li style="text-align: justify;">Phone number.</li>
<li style="text-align: justify;">Website URL.</li>
<li style="text-align: justify;">Email</li>
</ul>
<div style="text-align: justify;">
The actual Legal Notices appear after the contact details. Here's a list of notices that are most commonly used.</div>
<ul style="text-align: left;">
<li>Copyright notice.</li>
<li>Terms of use including any disclaimers.</li>
<li>A mention of industry standards and warnings, if applicable.</li>
<li>A note about trademarks.</li>
</ul>
</div>
<div>
<div style="text-align: justify;">
<br /></div>
</div>
<h3 style="text-align: justify;">
<span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;">Preface</span></h3>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial"; font-size: 14.6667px; white-space: pre-wrap;">The Preface is usually a single chapter and contains the following details:</span></div>
</div>
<div>
<ul style="text-align: left;">
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">What this guide contains: A brief description of what this user guide contains.</span></span></li>
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Intended audience: A brief description of the intended audience and assumptions about the domain and technical knowledge they need to use the manual effectively.</span></span></li>
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Providing feedback about the user guide: An email address where users can provide feedback about the user guide.</span></span></li>
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Typographical Conventions.: Describes the various fonts used in the document and what they signify.</span></span></li>
</ul>
</div>
<h3 style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;"><br /></span></span></h3>
<h3 style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Table of Contents</span></span></h3>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">In digital documents, it is a good practice to have a Table of Contents with page numbers and links to various chapters. </span></span><br />
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;"><br /></span></span> <span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">You can decide how deep you want to nest the table of contents. I suggest including the main sections of each chapter. Going one level below the chapters adds value but going deeper than that might just add clutter.</span></span></div>
</div>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;"><br /></span></span></div>
</div>
<h3 style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Introduction</span></span></h3>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">The Introduction is the first real-content chapter in the user manual. It is usually a single chapter but if the contents are large enough then it could be broken down into multiple chapters. A typical Introduction contains the following details:</span></span></div>
</div>
<div>
<ul style="text-align: left;">
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">A high-level explanation of the business domain, the value proposition of the software, important concepts, and terminology.</span></span></li>
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">High-level architecture/design diagram with a brief description of its components.</span></span></li>
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">What's new in this version.</span></span></li>
</ul>
</div>
<div>
<div style="text-align: justify;">
<h3>
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;"><br /></span></span></h3>
<h3>
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">System Requirements</span></span></h3>
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Many user guides include System Requirements in the Introduction but I prefer it to be a separate chapter by itself. This chapter lists the minimum hardware and software requirements to run the software.</span></span></div>
</div>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;"><br /></span></span></div>
</div>
<h3 style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Installation and Setup</span></span></h3>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">This section is usually split into multiple chapters. They contain the following details:</span></span></div>
</div>
<div>
<ul style="text-align: left;">
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Installing the software, along with any special setup instructions</span></span>.</li>
<li style="text-align: justify;"><span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Uninstalling the software.</span></span></li>
</ul>
<div>
<div style="text-align: justify;">
<br /></div>
</div>
<h3 style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Administration</span></span></h3>
</div>
<div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">The Administration section is usually split into multiple chapters. It describes all the features that contribute towards administering and maintaining the product. This includes features such as creating and managing users; managing security and permissions; managing quotas; networking; various rules; etc.</span></span></div>
</div>
<div>
<div style="text-align: justify;">
<br /></div>
</div>
<div>
<h3 style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Using the Software</span></span></h3>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">This section contains a description of the features available to regular users of the software. It describes everything a user can do with the software. This section is usually split into multiple chapters.</span></span></div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;"><br /></span></span></div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">Most user guides follow a sequence of the menu items and other UI elements. A high-level grouping of the topics can be done based either on user stories or on high-level menu items.</span></span></div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;"><br /></span></span></div>
<div style="text-align: justify;">
<span style="font-family: "arial";"><span style="font-size: 14.6667px; white-space: pre-wrap;">A good user guide may also provide background information about the concepts that a user should understand to use the software well.</span></span></div>
<div style="text-align: justify;">
<br /></div>
<h3 style="text-align: justify;">
Troubleshooting </h3>
<div style="text-align: justify;">
All software has known issues and known pitfalls. The Troubleshooting section describes various issues a user might face while using the software and how to overcome them. This section may be split into multiple chapters for troubleshooting the installation and troubleshooting usage issues.</div>
<div style="text-align: justify;">
<br /></div>
<h3 style="text-align: justify;">
Getting Help</h3>
<div style="text-align: justify;">
This chapter describes what a user should do if the troubleshooting instructions do not solve their problem. You would typically include the following information in this section:</div>
<ul style="text-align: left;">
<li style="text-align: justify;">A brief mention of all the log files, where to find them, and what they contain.</li>
<li style="text-align: justify;">Details of online support forums that your company hosts or supports.</li>
<li style="text-align: justify;">Information about how to reach customer support and the details that should be included in the support request for speedy resolution. These details are usually screenshots of the problem along with appropriate log files.</li>
</ul>
<div style="text-align: justify;">
<br /></div>
<h3 style="text-align: justify;">
</h3>
<h3 style="text-align: justify;">
Quickstart Guide</h3>
<div style="text-align: justify;">
For a complex software, the Quickstart Guide contains the most basic information that a user needs to know to get started with the product. A Quickstart Guide follows the philosophy that underlies the design of many software products: make basic features easy to use and complex features possible to use. The quickstart guide contains a description of the basic features. You can also think of this section as the <i>'Start Using Software X Within an Hour'</i> guide. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
Unless it's really short, the Quickstart Guide should be bundled as a separate document.</div>
<div style="text-align: justify;">
<br /></div>
<h3 style="text-align: justify;">
Working Examples</h3>
<div style="text-align: justify;">
This section is useful if your software supports an API or has an in-built scripting interface. It contains working examples of how to use the API and/or the scripting language. It's usually a good idea to bundle this section as a separate document.</div>
<div style="text-align: justify;">
<br /></div>
<h3 style="text-align: justify;">
Appendix</h3>
<div style="text-align: justify;">
The Appendix contains additional information that is useful to the user. It may also contain information that cannot be cleanly mentioned anywhere else in the manual. Here are some examples of what you might want to include in your Appendix:</div>
<div>
<ul style="text-align: left;">
<li style="text-align: justify;">Glossary of important terms.</li>
<li style="text-align: justify;">Keyboard shortcuts.</li>
<li style="text-align: justify;">Error codes. </li>
<li style="text-align: justify;">Function reference.</li>
</ul>
<div style="text-align: justify;">
<br /></div>
</div>
</div>
</div>
</div>
Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-80801634481914969702018-02-22T09:33:00.001+05:302018-04-11T22:28:13.090+05:30Planning a User Guide - Part 1/5 - Audience Analysis<div dir="ltr" style="text-align: left;" trbidi="on">
<div class="separator" style="clear: both; text-align: center;">
<a href="https://2.bp.blogspot.com/-82aACkMmxHw/Wo2qOmzUQiI/AAAAAAAAApk/n4RRwuhqVGkbNfVpIqmyiDrmLuAJ_fGHACLcBGAs/s1600/taras-shypka-424932-unsplash.jpg" imageanchor="1" style="margin-left: 1em; margin-right: 1em;"><img border="0" data-original-height="1067" data-original-width="1600" height="426" src="https://2.bp.blogspot.com/-82aACkMmxHw/Wo2qOmzUQiI/AAAAAAAAApk/n4RRwuhqVGkbNfVpIqmyiDrmLuAJ_fGHACLcBGAs/s640/taras-shypka-424932-unsplash.jpg" width="640" /></a></div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
Creating a User Guide is in many ways similar to building software. Just like software, creating a successful manual also needs prior planning. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
Planning a User Guide is a large topic so I’ll write it as a series of eight posts - one for each planning task.</div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
Here’s the first post on audience analysis.</div>
<div style="text-align: justify;">
<br /></div>
<h3 style="text-align: justify;">
Audience Analysis</h3>
<div style="text-align: justify;">
A User Guide explains how to install and use the product. An effective User Guide does it in a way that is easy and clear for its readers. It considers the goals and requirements of the users. Therefore, the first planning task is to understand the target audience.</div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
The best way to understand your users is to interview them. The interview is done to identify usage patterns and a set of attributes that will help you communicate more effectively with your target audience.<br />
<br />
You can begin by identifying a few (let’s say five) users and interview them to understand their requirements. If you already have a few pilot or actual customers then it's best to begin with them. However, if you don’t have customers as yet, then the interviews can be done with people you already know and who might fit the profile of a typical user. Old colleagues, family, and friends are usually happy to help. You can also tap into your LinkedIn network. It might reveal interesting people who may not have crossed your mind. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
The outcome of user interviews is a set of models that will help you understand your customers. <a href="https://en.wikipedia.org/wiki/Persona_(user_experience)" target="_blank">User Personas</a> are a great way to model your target audience. Aurora Harley gives a nice definition in <a href="https://www.nngroup.com/articles/persona/" target="_blank">this article</a>:</div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
<blockquote class="tr_bq">
A persona is a fictional, yet realistic description of a typical or target user of the product. A persona is an archetype instead of an actual living human, but personas should be described as if they were real people.</blockquote>
</div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
In software terminology, a persona can be thought of as an abstraction of a group of people who belong to the same user type. It contains those characteristics, of the group, that are important for building a better product - in this case, the user guide. However, a persona is more than just an abstraction. It is an attempt to make the abstraction personal and realistic. A typical abstraction might describe a user in dry, statistical terms. But a persona makes the description more human, helping us to not only understand but also empathize with the user and their requirements.</div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
Unless your software is for a very niche audience, you will most likely need multiple personas - one for each type of user. Realistically, I suggest creating about 3 - 5 personas. If you are building an enterprise software then you also need to create personas for the system admins who will install and manage the system. My suggestion is to create 2 - 3 system administrator personas in addition to user personas. Usually interviewing 2 - 3 people for each persona should be sufficient. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
From the perspective of a user guide, a typical persona would have the following details:</div>
<ul style="text-align: left;">
<li style="text-align: justify;">Personal details such as age, gender, and educational background.</li>
<li style="text-align: justify;">Professional details such as occupation and experience.</li>
<li style="text-align: justify;">Knowledge of the business domain and terminology. </li>
<li style="text-align: justify;">Needs</li>
<ul>
<li style="text-align: justify;">Does the user have any special needs?</li>
<li style="text-align: justify;">On what device do they typically access the User Guide and the product? </li>
<li style="text-align: justify;">Does the user use this software for work or is it for personal use?</li>
<li style="text-align: justify;">Any other needs the user has.</li>
</ul>
<li style="text-align: justify;">Goals when working with the product: speed, accuracy, thoroughness, etc.</li>
<li style="text-align: justify;">A photograph of a typical user: You can photograph an actual user or pull out a stock photo that most closely resembles the details you've gathered. Having a photo may seem insignificant but it’s not. A photograph will make it easier for your team to empathize with the user.</li>
</ul>
<div style="text-align: justify;">
Once ready, the user personas can be used as a reference point for making decisions related to the manual’s design and content. For example, personal details of the user will help in determining the choice of words and the tone of the manual. A User Guide written for an audience in their 60s and 70s will use a different set of words than a User Guide written for an audience primarily in their 30s. You might also want to use a larger font for the former. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
If most of the users read the manual on their mobile device then you would avoid a multi-column design. You would also avoid margin notes. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
It’s important to know how familiar users are with the business domain and terminology. This point is really important because a typical manual contains a lot of terminologies. We often assume familiarity but it’s often not the case. It’s good to know which words and concepts the users might have to struggle with so they can be included in the glossary. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
A product made for hobbyists might have a manual that explains a lot of background concepts and provides useful tips, while a manual centered around business users will be more to the point and formal. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
These are just some ways to use the information from user personas - you’ll create your own rules as you go along. The key is to ask yourself questions like:<br />
<br />
<ul>
<li>Will this cover design appeal to Emily and John?</li>
<li>Will Mr. Watkins be able to read this font style? Are the margins and spacing comfortable for him?</li>
<li>Ms. Shaw does not have much time on her hands. Is the information I am writing concise enough for her?</li>
</ul>
It’s really about making it a barrier-free experience for the users. </div>
<div style="text-align: justify;">
<br /></div>
<div style="text-align: justify;">
Finally, user personas serve as a terminology for discussions, much like design patterns do in software architecture related discussions. In software architecture discussions, using a pattern name such as ‘The Singleton Pattern’ or ‘MVC Pattern’ allows the speaker to use a name that expands into concepts that would have otherwise taken a lot of explaining. Similarly, in User Guide related discussions, a writer might say - “I think this decision will be perfect for Emily’s needs.” The user persona referenced to by “Emily” expands to all the needs described in that persona without having to mention each of them individually.<br />
<br />
In conclusion, begin your User Guide with a planning phase to ensure that it's easy for your users to use and understand. Getting to know your target audience is the first planning step. We use User Personas to model types of users and then subsequently these personas in discussions and while writing the User Guide.<br />
<br />
Here are three articles that you can read for more information on User Personas:<br />
<br />
<ol>
<li><a href="https://knowledge.hubspot.com/contacts-user-guide-v2/how-to-create-personas" target="_blank">How to create personas (HubSpot Academy)</a></li>
<li><a href="https://99designs.com/blog/business/how-to-create-user-personas/" target="_blank">How to create a user persona (99 Designs)</a></li>
<li><a href="https://conversionxl.com/blog/creating-customer-personas-using-data-driven-research/?hvid=2AD8ar" target="_blank">How To Create Customer Personas With Actual, Real. Life Data</a></li>
</ol>
</div>
<div style="text-align: justify;">
In the next blog post, I will explain how to define the overall scope of the User Guide.</div>
</div>
Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-53870860144610256962018-02-13T22:45:00.003+05:302018-02-22T09:42:33.813+05:30Five Reasons Why Your Product Needs an Awesome User Guide<div dir="ltr" style="text-align: left;" trbidi="on">
<a data-flickr-embed="true" href="https://www.flickr.com/photos/peterme/1253700105/in/photolist-2UMxn4-2u1gN-2US4pf-7RUwTJ-pDMM7S-pE1YbZ-6BeEZR-618vpm-qjemss-7svt3U-6tuV8D-4nMqNW-qje6P9-ntSsFP-rcijkj-5eLceA-naBjH7-naBoSb-A97yK-9T9pm-rRw1G-6Vza63-oMsNA-hR6nvM-DSpjTM-o8XYuK-9nx6d4-8zjiL1-4bqz4P-f5p52P-5YUzTm-foUbWr-cBTGnd-rWPaZ-eehH9S-baW6Ka-9hQAR2-aEVxwG-ntSt8R-pQNL1S-rmWHpR-5aWfCx-GQVRkP-9YymkX-yichy-fp9x6J-foUaTp-foUcu6-foUcBp-fp9uRG" title="Macintosh User Manual - Clicking"><img alt="Macintosh User Manual - Clicking" height="399" src="https://farm2.staticflickr.com/1275/1253700105_c3e26fbf8d_z.jpg" width="640" /></a><script async="" charset="utf-8" src="//embedr.flickr.com/assets/client-code.js"></script>
<br />
<div dir="ltr" style="text-align: left;" trbidi="on">
<div style="text-align: center;">
<span style="font-size: x-small;"><i><a href="https://flic.kr/p/2UMxn4" target="_blank">Photo Credit: Peter Merholz</a> (<a href="https://creativecommons.org/licenses/by-sa/2.0/" target="_blank">Creative Commons 2.0 SA License</a>)</i></span></div>
<br />
<blockquote class="tr_bq">
A user guide is essentially a book-length document containing instructions for installing, using or troubleshooting a hardware or software product. A user guide can be very brief - for example, only 10 or 20 pages or it can be a full-length book of 200 pages or more. -- <a href="https://www.prismnet.com/~hcexres/textbook/user_guides.html" target="_blank">prismnet.com</a></blockquote>
<div style="text-align: justify;">
As engineers, we give a lot of importance to product design, architecture, code quality, and UX. However, when it comes to the user manual, we often only manage to pay lip service. This is not good. A usable manual is as important as usable software because it is the first line of help for the user and the first line of customer service for the organization. Any organization that prides itself on great customer service must have an awesome user manual for the product.</div>
<div style="text-align: justify;">
In the spirit of listicles - here are at least five reasons why you should have an awesome user manual!</div>
<div style="text-align: justify;">
<br />
<br />
<h3>
Enhance User Satisfaction</h3>
</div>
<div>
<br /></div>
<div style="text-align: justify;">
In my fourteen years as a software developer, I have often been in situations where something just wouldn't work in a software I was using. When this happens, I usually try a few quick hacks and if they didn't work either, I reach for the user manual. I consider the user manual to be the first line of support and I open it with part hope and part trepidation. There have been times -- God bless the team who wrote it -- when the manual pointed me to the solution immediately. The feeling I have at such times is unmistakable. There is a sense of relief; a sense of joy; and a sense of gratitude. It is very satisfying. I say a silent <i>thank you</i> to the team for making my life easier. I feel glad I purchased that software instead of the alternatives.</div>
<div>
<div style="text-align: justify;">
I'm sure most people feel that way and yet when it is our turn to write the manual, we somehow miss out on its importance. </div>
</div>
<div style="text-align: justify;">
If you value user satisfaction - make sure your product has a great manual.<br />
<br />
<h3>
</h3>
<h3>
Reduce Support Overhead</h3>
<div>
<br /></div>
<div>
I have also been on the other side of the table where I have had to talk with bewildered customers who were stuck with issues they couldn't fix. These calls typically took anywhere from fifteen minutes to an hour. Add to that the cost of context switching from my work and the overall cost of a sloppy User Guide is fairly heavy.</div>
<div>
Granted that developers don't have to get on customer support calls in most organizations (although they do in most startups) it's still someone's time spent that could have been saved with a better manual.</div>
<div>
Whether it's developer time or the time of the support staff - lost time translates directly to cost. Not only that, it also results in a lost opportunity to give more timely support if the support team gets swamped. </div>
<div>
<br />
<br /></div>
</div>
<h3 style="text-align: justify;">
Increase Sales</h3>
<div style="text-align: justify;">
By now enough people have burned their fingers with buggy or unusable software. A good user manual is no longer seen as an added benefit. It's a <i>must-have</i> for many customers. I have always considered the user manual as an important factor when evaluating software for a purchase decision and I suspect many people will consider it to be an important factor before closing the deal.</div>
<div style="text-align: justify;">
Another way user manuals impact sales is through the satisfaction of existing customers. Satisfied customers are some of your best evangelists. They will talk about the product with other people which can generate sales with little or no effort from the sales team.</div>
<div style="text-align: justify;">
<br />
<br /></div>
<h3 style="text-align: justify;">
Create a Great Image for Your Product and Company</h3>
<div style="text-align: justify;">
Scott Cooley <a href="https://www.deque.com/blog/user-documentation-important/" target="_blank">considers documentation to be a maturity indicator</a>. How true! It takes a mature company to understand the importance of great documentation and also allocate resources to actually create it.</div>
<div style="text-align: justify;">
It's also an indicator of how much your company values the customer's time. All organizations declare satisfaction as their #1 priority. Here's a simple way to actually demonstrate it.</div>
<div style="text-align: justify;">
Finally, a beautifully written user manual adds that extra X-factor to the image of the product. Producing great user documentation is an effective way to enhance the brand value of your company.</div>
<div style="text-align: justify;">
<br />
<br /></div>
<h3 style="text-align: justify;">
Limit Legal Liability Related to Misuse of the Product</h3>
<blockquote class="tr_bq">
<div style="text-align: justify;">
You are liable if people hurt themselves while using your product and you haven't provided them with the means to avoid it. -- <a href="http://technicalwriting.eu/benefit-from-a-good-user-manual/" target="_blank">technicalwriting.eu</a></div>
</blockquote>
<div style="text-align: justify;">
<div style="-webkit-text-stroke-width: 0px; color: black; font-family: "Times New Roman"; font-size: medium; font-style: normal; font-variant-caps: normal; font-variant-ligatures: normal; font-weight: 400; letter-spacing: normal; orphans: 2; text-align: justify; text-decoration-color: initial; text-decoration-style: initial; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px;">
<div style="margin: 0px;">
This one's probably more important for hardware products or software products that handle machinery or critical health-related equipment. If you do have a critical product it is your duty to write a manual that clearly outlines appropriate usage and safety instructions. But even if you aren't shipping critical software, it's still a good idea to describe the correct way to use your product.</div>
</div>
</div>
<div style="text-align: justify;">
<br /></div>
<h3 style="text-align: justify;">
</h3>
<h3 style="text-align: justify;">
Summing it up</h3>
<div>
<br /></div>
<div>
We all know the benefits of great user documentation, but somehow deadline pressures make us complacent. However, if you consider the cost and opportunity benefit that accrues from:</div>
<div>
<ol style="text-align: left;">
<li>Enhanced user satisfaction</li>
<li>Reduced support overhead</li>
<li>Increased sales</li>
<li>Improved branding</li>
<li>Limited legal liabilities</li>
</ol>
<div>
- you will agree that it's a no-brainer to put in additional time and resources for creating awesome User Guides.</div>
</div>
<div>
<br /></div>
</div>
</div>
Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-88322485018137582952012-09-27T13:57:00.000+05:302012-09-27T13:57:42.218+05:30Fuctional Programming Principles in Scala - Getting Started<div dir="ltr" style="text-align: left;" trbidi="on">
Sometime back I registered for the <a href="https://class.coursera.org/progfun-2012-001/class/index" target="_blank">Functional Programming Principles in Scala</a>, on Coursera. I have been meaning to learn Scala from a while, but have been putting it on the back burner because of other commitments. But when I saw this course being offered by Martin Odersky, on <a href="http://www.coursera.org/" target="_blank">Coursera</a>, I just had to enroll in it.<br />
<br />
This course is a 7 week course. I will blog my learning experience and notes here for the next seven weeks (well actually six, since the course started on Sept 18th).<br />
<br />
The first step was to install the required tools:<br />
<ul style="text-align: left;">
<li>JDK - Since this is my work machine, I already have a couple of JDK's installed</li>
<li>SBT - SBT is the Scala Build Tool. Even though I have not looked into it in detail, it seems like a replacement for Maven. I am sure we will use it for several things, however upto now I only know about two uses for it - to submit assignments (which must be a feature added by the course team), and to start the Scala console. Installed sbt from <a href="http://scalasbt.artifactoryonline.com/scalasbt/sbt-native-packages/org/scala-sbt/sbt/0.12.0/sbt.tgz" target="_blank">here</a>, and added the path to it's bin directory in my .bashrc file. When I first started sbt, I did not realize that sbt would need to connect to the Internet to download it's dependencies. My computer was disconnected from the Internet, which caused sbt to give up. This is the first time I realized that sbt seems to be doing something that I would expect Maven to do.</li>
<li> Next, I installed the <a href="http://typesafe.com/stack/scala_ide_download" target="_blank">Scala IDE</a>, which seems to be Eclipse with a Scala plugin. Since I already have Eclipse, I wonder if I cold have simply installed a plugin.</li>
</ul>
Once I had the tools setup ready, I created a workspace for all my DIYLearning courses (since I plan to always be enrolled on at least one course, from Coursera, Udacity, edX, or any other open courseware offering that is good).<br />
<br />
Then I downloaded the example project, made a few modifications to it, ran unit tests and submitted it. I learned quite a few things by wandering around this example project.<br />
<br />
<b>Directory structure is similar to Maven:</b><br />
The directory structure of the projects is similar to what it might have been had I used Maven. The sources were in 'src/main/scala', and tests in 'src/test/scala'. sbt seems to have a directory structure similar to Maven. I like that. It does not make sense to relearn everything from scratch for every single tool.<br />
<br />
<b>Scala imports are slightly different</b><br />
This is how Scala imports everything from a namespace. Notice how they have deviated from Java imports by using the '_' character for the wildcard. I asked a question on the forum, and was told that functional programming languages by convention use the '_' character for wildcards. So ok, that too makes sense.<br />
<br />
<pre>import Lists._</pre>
<br />
<br />
<b>Unit tests in Scala</b><br />
Unit tests in Scala look similar to unit tests in Java, but there are a few things which stand out as different. Scala uses ScalaTest, as the unit testing tool in Scala. To create a ScalaTest test case, we have to extend FunSuite. Their website also mentions something about traits. I have heard this term before, but do not really know what it is. Need to look into what it really means. I also noticed that ScalaTest's have only one type of assert, which is equivalent to assertTrue. This also makes sense to me, because everything can be reduced to an assertTrue assertion.<br />
<br />
ScalaTest introduces an operator called 'test'. This operator takes two arguments, the first one being the name of the test, and the second one being the body of the test. The body usually consists on an assert. Here is how a test operator looks<br />
<br />
<pre>test("testing equality")(assert(1==1))</pre><br />
<br />
The body of the test can also be given as a block, which makes it more readable.<br />
<br />
<pre>test("testing equality") {assert(1==1)}</pre><br />
<br />
<br /></div>
Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com1tag:blogger.com,1999:blog-7520738.post-79534587186139712022012-04-05T15:58:00.006+05:302012-04-05T16:29:50.086+05:30Creating an Eclipse web project using Maven and Struts 1.xI am doing some Struts work after a long time. Interestingly it is for a <b><i>Test Driven Development</i></b> training. A client wants me to do a hands on session, using Struts 1.x, and EJB's. They also want to do the hands on sessions with a small but production project. It seems their developers are tired of Calculator and Shape projects :-) Well I can't really blame them.<div><br /></div><div>I have been planning to create some micro applications around diycomputerscience.com . I hope to create each application using a different technology, so I can have several reference points for teaching. </div><div><br /></div><div>For this session I am going to make a web application which will store and display my slides. I am sure you are thinking ... <i>but why not just use SlideShare ?</i> Well besides the fact that I think this makes a great application that is small, but also production quality. Ideal for using to teach. But there are other reasons as well. It is very hard to embed code snippets on Slideshare. Slideshare also does not support comments per slide.</div><div><br /></div><div>Since I started working with Maven sometime back, I thought, why not use Maven for dependency and build management for this project. </div><div><br /></div><div>While creating an Eclipse web project for Struts 1.x using Maven led me to some issues, and I feel it might help others if I documented them.</div><div><br /></div><div>The first thing I needed to do was to find a Maven archetype for creating a Struts project. Interestingly the Struts 1.x archetype has been removed from the Maven 2 repository. So, I downloaded the archetype from <a href="http://svn.apache.org/repos/asf/struts/maven/trunk/struts-archetype-blank">this</a> repository. Then I did a 'mvn install' to install the archetype in my local Maven repository.</div><br /><br /><pre class="adaptiveconsole"><div>svn co http://svn.apache.org/repos/asf/struts/maven/trunk/struts-archetype-blank</div><div>cd struts-archetype-blank</div><div>mvn install</div><div><br /></div><br /></pre><br /><div><br /></div><div>Then I created my Struts project, and used maven's eclipse plugin to generate Eclipse proejct files.</div><div><br /></div><br /><div><br /><div><br /><pre class="adaptiveconsole">mvn archetype:generate -DarchetypeGroupId=org.apache.struts -DarchetypeArtifactId=struts-archetype-blank -DarchetypeVersion=1.3.5-SNAPSHOT -DgroupId=com.diycomputerscience -DpackageName=com.diycomputerscience.stslides -DartifactId=struts-slides<br /></pre></div><br /></div><br /><div><br /></div><br /><div><br /><pre class="adaptiveconsole">mvn eclipse:eclipse<br /></pre><br /></div><br /><br /><div><br /></div><div>However, when I tried running the project, I realied that this project was not an Eclipse dynamic web project. That's not good because I wanted to run it from within Eclipse. A bit of searching led me to <a href="http://www.mkyong.com/maven/how-do-use-maven-to-create-a-dynamic-web-project-in-eclipse/">this</a> post which explained that I needed to run </div><div><br /></div><div><br /><pre class="adaptiveconsole">mvn eclipse:eclipse -Dwtpversion=2.0<br /></pre><br /></div><div><br /></div><div>Now all seems to be fine. I have a Struts 1.x dynamic web project which is managed by Maven and can be run within Eclipse.</div>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com1tag:blogger.com,1999:blog-7520738.post-76108764920277817372011-06-06T13:45:00.004+05:302011-06-06T15:37:45.660+05:30Running your own one person companyRecently there was a post on PuneTech on mom's re-entering the IT work force after a break. Two of the biggest concerns mentioned were :<br /><ul><li>Coping with vast advances (changes) in the IT landscape</li><li>Balancing work and family responsibilities</li></ul>Since I have been running a one person company for a good amount of time, I suggested that as an option. In this post I will discuss various aspects of running a one person company.<div><br /></div><div><b>Advantages:</b></div><div><ul><li>You have full control of your time. You can choose to spend as much or as little time as you would like. There is also a good chance that you will be able to decide when you want to spend that time. </li><li>You get to work on something that you enjoy doing. Tremendous work satisfaction.</li><li>You have the option of working from home.</li></ul><div><b>Disadvantages:</b></div></div><div><ul><li>It can take a little while for the work to get set, so you may not be able to see revenues for some time.</li><li>It takes a huge amount of discipline to work without a boss, and without deadlines.</li><li>You will not get the benefits (insurance, etc) that a company would give you.</li><li>Your finances may or may not show a constant graph.</li><li>You may have a hard time getting home loans, since most banks (especially in India) feel that employed people are more stable (whatever that means :-) )</li><li>People may think you are not doing <b><i>real work</i></b> (most people have a very skewed notion of what real work means)</li><li>You will have to deal with distractions, if you are working from home.</li></ul><div>Even though the disadvantages outnumber the advantages, qualitatively I think the advantages are vast. I may be a bit biased, but I really think that a 9 - 5 job in a large organization, totally sucks the soul out of a person.</div></div><div><br /></div><div><b>Legal</b></div><div>I will restrict this advise to India, whose laws I am accustomed with. You do <b>not</b> need to register any legal entity to run a one person business. You can run it on your own name, you can raise invoices on your own name, and you can file your taxes on your personal PAN number.</div><div><br /></div><div>Some people may create a sole proprietorship, but that is purely to have a business name and to be able to invoice clients on a business name, rather than your personal name. Besides this, having a sole proprietorship has the advantage of being able to easily separate personal and business accounts. The latter can be achieved simply by keeping a separate savings account for work related transactions. </div><div><br /></div><div>Some people may also choose to create an LLP. Besides the points mentioned for sole proprietorship,an LLP will shield your personal finances against business losses, lawsuits, etc.</div><div><br /></div><div>I will not get into the legalities of creating a sole proprietorship, or LLP. My suggestion is to start work on your personal name, and create a legal entity later, if required. You should consult your CA for details of creating a business entity.</div><div><br /></div><div><b>Types of work</b></div><div>There are many types of work that can be done as a one person business. I will focus on IT related fields in this post. </div><div><br /></div><div><b>Freelancing:</b> </div><div>Many people make a living by doing freelance projects. You can either get projects directly from clients, or you can work on one of many freelancing websites. These websites publish projects that people want completed. If you feel that you can do the project, then you can bid for it. If you get the project, you will have to complete it in the stipulated time, and with the required features. The payment usually comes once the client is satisfied with the work. Most of these websites allow the client as well as the developer to rate each other. These ratings go a long way in determining whether a client will give you projects. Typically a freelancing website have work related to coding, documentation, website design, etc. Some such websites are: <a href="elance.com/">Elance</a>, <a href="http://www.vworker.com/?txtFromURL=AId_7889766">vWorker.com</a>, <a href="http://freelanceswitch.com/">FreelanceSwitch</a>, <a href="https://www.odesk.com/">ODesk</a>, and <a href="http://www.freelancer.com/affiliates/adaptives/">freelancer.com</a>. <b><i><span class="Apple-style-span" style="font-size: small;">(Disclosure: I will get a small commission if you register on some of these websites, following the provided link)</span></i></b></div><div><br /></div><div>Regardless, of whether you get projects from a freelancing website, or on you own, you should always have your own website, and a blog. I cannot stress how important it is for a freelancer to have a blog. Your blog is the place where potential clients and friends get a glimpse of the real you. It is also your showcase for projects completed, and an online portfolio.</div><div><br /></div><div><div><b>Contract programming:</b></div><div>If you have been in the software industry for a long while, then you probably already have a lot of contacts who would like to give you some contract programming work. This can also be lucrative and fun. In contract programming you typically make a commitment (such as 20 hours per week), and charge on an hourly rate.</div></div><div><br /></div><div><b>Teaching:</b></div><div>If have passion for sharing your knowledge with others, then teaching is a wonderful way to do satisfying work and earn a livelihood. There are various avenues for teaching. You can teach in a local college, you can teach at companies, or you can teach on the Internet. You can also do all of these if you desire. </div><div><br /></div><div>Some places you can create courses and teach on the web are, <a href="http://edufire.com/">edufire.com</a>, and <a href="http://wiziq.com/">wiziq.com</a>. You can also create your own website for teaching using <a href="http://www.moodle.org/">Moodle</a>, or a similar open source software. I have created my own <a href="http://diycomputerscience.com/">website for teaching computer science</a>, but I am not yet making any significant revenue from it, so beware before you take it as a role model :-) However, you can check out this website of a <a href="http://use-the-index-luke.com/">database expert</a> who maintains a learning community on his website.</div><div><br /></div><div>You can also create and sell screencasts like the people at <a href="http://peepcode.com/screencasts">Peepcode</a>, and <a href="http://destroyallsoftware.com/">Destroy all software</a>.</div><div><br /></div><div> I think there is a lot to be said about teaching, and it probably warrants a separate blog post.</div><div><br /></div><div><b>Creating mobile applications:</b></div><div>Many people make a living by creating mobile applications, for Android, iPhone, etc. The amounts vary, but it is very much do-able. Several people give helpful tips and also post there monthly incomes on their blogs. You might find them useful. This is <a href="http://www.kreci.net/">one example website</a> of an independent developer who posts monthly incomes and also gives helpful tips.</div><div><br /></div><div><b>Creating stock photos, and designs:</b></div><div>If you are the arty type, you can create stock photos, images, or icons, and put them up for sale on stock photo websites. There are many such websites, and some people are able to make a good continuous stream of income from them. <a href="http://www.istockphoto.com/">iStockPhoto</a> is one such website. You can also create designs for clients on sites like <a href="http://99designs.com/">99designs.com</a>.</div><div><br /></div><div><b>Selling websites:</b></div><div>If you enjoy making and selling websites, you can make and auction your websites on <a href="https://flippa.com/">Fippa.com</a>.</div><div><br /></div><div><b>Niche websites:</b></div><div>If you are really passionate about something, and also have a lot of knowledge in that field, then you can share your knowledge on a niche website, and earn revenues from advertisements, affiliate sales, subscriptions, etc. See <a href="http://www.smartpassiveincome.com/nichesiteduel/">this blog post</a> on information about building niche websites.</div><div><br /></div><div><b>E-Commerce:</b></div><div>If you have something to sell, you can also set up shop using a hosted e-commerce solution. However, keep in mind that managing logistics, shipping, handling, and customer care may be more than what one person can handle.</div><div><br /></div><div>I hope you found this post useful. This is a brief list of things that can be done as a one person entity, and some pointers on how to go about doing it. I think plenty more can be said on this topic. </div><div><br /></div><div>I will try and write further blog posts talking about each of these points in greater detail. </div>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com10tag:blogger.com,1999:blog-7520738.post-76785935857662942222011-04-27T17:17:00.001+05:302011-04-27T17:20:45.678+05:30My HSQLDB schema inspection story<p>This is a simple story of my need to inspect the schema of an HSQLDB database for a participar FOREIGN KEY, and the interesting things I had to do to actually inspect it.</p><br /><br /><p><br />I am using an <a href="http://hsqldb.org/">HSQLDB 1.8</a> database in one of my web applications. The application has been developed using the <a href="http://www.playframework.org/">Play framework</a>, which by default uses <a href="http://www.oracle.com/technetwork/articles/javaee/jpa-137156.html">JPA</a> and <a href="http://www.hibernate.org/">Hibernate</a>. <br /></p><br /><br /><p><br />A few days back, I wanted to inspect the schema which Hibernate had created for one of my model objects. I started the HSQLDB database on my local machine, and then started the database manager with the following command<br /></p><br /><br /><code>java -cp ./hsqldb-1.8.0.7.jar org.hsqldb.util.DatabaseManagerSwing</code><br /><br /><p><br />When I tried the view the schema of my table, it showed me the columns and column types on that table, but it did not show me columns were FOREIGN KEYs.<br /><a href="http://tinypic.com?ref=2rgm353" target="_blank"><img src="http://i52.tinypic.com/2rgm353.jpg" border="0" alt="Image and video hosting by TinyPic"></a><br /><div><i>Image 1: Table schema as shown by HSQLDB's database manager</i></div><br /></p><br /><br /><p><br />I decided to search on <a href="http://www.stackoverflow.com">StackOverflow</a> and find out how I could view the full schema of the table in question. I got a few hints, and they all pointed to the system tables, so I decided to turn on the "show system tables" option from HSQLDB's view menu.<br /></p><br /><br /><p><br />The first table that caught my eye was <strong>information_schema.system_tables</strong>, so I fired the query:<br /><div><br /><pre><br />select * from information_schema.system_tables;<br /></pre><br /></div><br /><div><br />This gave me all the system as well as application tables, but did not give me the detail I was looking for, which was the FOREIGN KEY contstraints on the 'USERREGISTRATIONDATE' table.<br /></div><br /></p><br /><br /><p><br />The next table that caught my eye was <strong>information_schema.system_table_constraints</strong>, so I fired the following query:<br /><div><br /><pre>select * from information_schema.system_table_constraints where table_name = 'USERREGISTRATIONDATE';</pre><br /></div><br /><div><br />This helped a bit further. It told me that the <strong>USERREGISTRATIONDATE</strong> table had a FOREIGN KEY and the constraint name was 'FK98DCB61247140EFE'.<br /><a href="http://tinypic.com?ref=15gjlc" target="_blank"><img src="http://i55.tinypic.com/15gjlc.png" border="0" alt="Image and video hosting by TinyPic"></a><br /><div><i>Image 2: Result from table INFORMATION_SCHEMA.SYSTEM_TABLE_CONSTRAINTS</i></div><br /><br/><br /></div><br /><div>Nice, but it still did not tell me which column the constraint refered to.</div><br /></p><br /><br /><p><br />The next table I came across was <strong>information_schema.system_crossreference</strong>. This seemed to have a column called 'FK_NAME'. Good, I fired the query:<br /><div><br /><pre>select * from information_schema.system_crossreference where FK_NAME='FK98DCB61247140EFE';</pre><br /></div><br /><div><br />Here is what this table showed me...<br /></div><br /><div><br /><a href="http://tinypic.com?ref=675b1f" target="_blank"><img src="http://i56.tinypic.com/675b1f.png" border="0" alt="Image and video hosting by TinyPic"></a><br /></div><br /><div><i>Image 3: Result from table INFORMATION_SCHEMA.SYSTEM_CROSSREFEREBCE</i></div><br /><br/><br /><div><br />Awesome, this time it showed me the name of the the FOREIGN KEY 'FK98DCB61247140EFE' references the 'ID' column of table 'USER'<br /></div><br /></p><br /><p><br />I finally had my answer, but before ending this post, let me mention just one more thing. I realized that I did not need the information_schema.system_table_constraints table at all. I only needed the information_schema.crossreference table with the following query:<br /><div><br /><pre><br />select PKTABLE_NAME, PKCOLUMN_NAME, FKTABLE_NAME, FKCOLUMN_NAME <br />from information_schema.system_crossreference <br />where FKTABLE_NAME='USERREGISTRATIONDATE' and FKCOLUMN_NAME='USER_ID';<br /></pre><br /></div><br /><br /><a href="http://tinypic.com?ref=25hhjq1" target="_blank"><img src="http://i53.tinypic.com/25hhjq1.jpg" border="0" alt="Image and video hosting by TinyPic"></a><br /><div><i>Image 4: Finally the query that clearly showed me the FOREIGN KEY</i></div><br /><br/><br /><div><br />Now all this should not have been so time consuimng. The GUI tool should have given me this information right away.<br /></div><br /></p>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-24391635759414770242010-10-15T15:49:00.007+05:302010-10-15T22:41:02.138+05:30Double Checked Locking And Java SingletonsI read this <a href="http://www.cs.umd.edu/~pugh/java/memoryModel/DoubleCheckedLocking.html">article</a> by <a href="http://www.cs.umd.edu/~pugh/">Bill Pugh</a> on why the <cite>double checked locking</cite> idiom does not guarantee thread safety in Java Singletons. That article taught me a lot of new things, and to be honest, I had to re-read that article at least a couple of times to partially understand it :-)<div><br /></div><div>I recently created a presentation to make at DevCamp on this topic. What follows are my slides and an explanation of each slide. I hope you enjoy this presentation and find it useful.<br /><br /><div style="width:425px" id="__ss_5450422"><strong style="display:block;margin:12px 0 4px"><a href="http://www.slideshare.net/parag/double-checkedlockingjavasingletons" title="Double checkedlockingjavasingletons">Double checkedlockingjavasingletons</a></strong><object id="__sse5450422" width="425" height="355"><param name="movie" value="http://static.slidesharecdn.com/swf/ssplayer2.swf?doc=doublecheckedlockingjavasingletons-101015051343-phpapp02&stripped_title=double-checkedlockingjavasingletons&userName=parag"><param name="allowFullScreen" value="true"><param name="allowScriptAccess" value="always"><embed name="__sse5450422" src="http://static.slidesharecdn.com/swf/ssplayer2.swf?doc=doublecheckedlockingjavasingletons-101015051343-phpapp02&stripped_title=double-checkedlockingjavasingletons&userName=parag" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="425" height="355"></embed></object><div style="padding:5px 0 12px">View more <a href="http://www.slideshare.net/">presentations</a> from <a href="http://www.slideshare.net/parag">parag</a>.</div></div><br /><b>slide 1:</b> </div><div>In this presentation I will discuss the <cite>double checked locking</cite> idiom, and explain why it does not work to provide thread safety to Java Singletons. I will also talk about how using volatile fields will fix the problem in JDK 1.5 onwards.<script src="http://b.scorecardresearch.com/beacon.js?c1=7&c2=7400849&c3=1&c4=&c5=&c6="></script><script src="http://b.scorecardresearch.com/beacon.js?c1=7&c2=7400849&c3=1&c4=&c5=&c6="></script><script src="http://b.scorecardresearch.com/beacon.js?c1=7&c2=7400849&c3=1&c4=&c5=&c6="></script></div><div><br /></div><div><b>slide 2 (Singleton):</b></div><div>Many of you might already have used the <a href="http://sourcemaking.com/design_patterns/singleton">Singleton design pattern</a>. In case you have not, here is a brief description of what Singletons are. The Singleton pattern is used when we want to ensure that there is only one instance of a class per something. In most cases, the something is 'JVM - Classloader' combination. So, in such cases we want to ensure that there is only one instance of the Singleton class in the JVM-Classloader. But we are not restricted to this. We may need only one instance of the Singleton per Session, or per Request, or per anything else that makes sense in the software you are making. </div><div><br /></div><div>It is clear that we want to control the instantiation process of the Singleton class. To do this, the first thing we do as shown in the example is to make the constructor private. With the constructor private, no other class can create an instance of this class. OK, so how will we create <b><i>any</i></b> instance of this class? We provide a public static method called <code>getInstance()</code> which will return an instance of this class. We will also use a private static field called instance to hold the one and only instance of this class. Since we control the <code>getInstance()</code> method, every time it is invoked we will return instance. The first time however, <code>instance</code> will not be initialized, so we put a null check in <code>getInstance()</code> and instantiate <code>instance</code> if it has not already been instantiated. Hence forth we will always return a reference to <code>instance</code>. This way we ensure that only one instance of our Singleton will be ever created (the one we save in the field called <code>instance</code>).</div><div><br /></div><div><b>slide 3 (Is This A Safe Singleton?):</b></div><div>Look at the class carefully and ask yourself "Is this Singleton safe?"</div><div><br /></div><div><b>slide 4 (The Singleton is not Threadsafe):</b></div><div>If you have looked at the class carefully, you will realize that the Singleton is not thread safe. This slide shows why it is not thread safe. Imagine that a thread T1 invokes <code>getInstance()</code>. If an instance of the Singleton has not been created till now, then <code>instance</code> will be null, and T1 will enter the if block. Now imagine that T1 gets pre-empted, and thread T2 also calls <code>getInstance()</code>. Since T1 got pre-empted before it got a chance to create <code>instance</code>, the reference in <code>instance</code> is still null. So T2 will also enter the if block. Now if T2 does not get pre-empted then it will go ahead all the way where it will create an instance of Singleton, and probably even use it. Now when T1 is resumed, unfortunately it does not know that the Singleton has already been created, since it has already gone past the null check. T1 will also happily create an instance of our Singleton, thus breaking the Singleton pattern. We have 2 instances of the Singleton which is simply not allowed.</div><div><br /></div><div><b>slide 5 (Let;s Make It Threadsafe):</b></div><div>Alright so we need to make the <code>getInstance()</code> method thread safe. The simplest way to do this is by making it synchronized. Once it is synchronzied, only one thread will be allowed to enter the method at a time, and we will never get into an issue where we end up having multiple instances of the Singleton.</div><div><br /></div><div><b>slide 6 (That Was Expensive):</b></div><div>Making a method synchronized is expensive. A thread executing a synchronized method must acquire a monitor before it can invoke the method, and release the monitor after executing the method. This takes time and CPU cycles. In early JVM's (I have read somewhere), the time to invoke (not execute) a synchronized method was as much as 100x the time taken to invoke a non synchronized method. I think this was improved in later JVM's where it was about 15x. I recently did a quick test on JDK 1.6, and the number I got was 2x. Regardless of how much slower it is, it is definitely slower, and programmers always want to make their code fast.</div><div><br /></div><div><b>slide 7 (Let's Use Double Checked Locking):</b></div><div>Some very smart programmers came up with the "double checked locking" idiom to relieve the code of this expensive operation. What we really should have done, is only synchronize the code which instantiates the Singleton, and not the entire method. That way we incur the expense of the synchronized block only once, when the Singleton needs to be created, and all subsequent times (instance == null) will always be false, and the instance will be returned to the calling code. We put a second check inside the synchronized block, because it is possible that a thread could get pre-empted just after the first null check, but before it enters the synchronized block. In such a case, if another thread enters this method, and goes all the way to creating the instance then the first thread will not know of it and will create a second instance. To prevent this, we put another check in the synchronized block. </div><div><br /></div><div>So this is a pretty smart solution. We eliminate the synchronization on the method, thus eliminating synchronization on the main path.</div><div><br /></div><div><b>slide 8 (Will It Work?):</b></div><div>The solution described in the previous slide (double checked locking) is a pretty smart solution. But it does not work.</div><div><br /></div><div><b>slide 9 (Why?):</b></div><div>There are two reasons why it does not work. The compiler as well as the processor (as well as the JVM) may reorder instructions if they feel it might be more optimal. Off course they cannot randomly reorder instructions but they could if they can prove that the reordering will maintain as-if-serial semantics. However, this is not the only reason. On a multi-processor system, each processor has it's own memory cache. The cache is not always synchronized with main memory immediately. This can cause a write to a memory location to happen in the local cache, which will not be visible to other threads which could be running on other processors. Even if the writing thread does flush it's local cache, it is still possible that another thread which reads that value, may not have pulled in most recent values from the main memory into it's local cache. This can cause a situation very similar to reordering where the effect of a write is not visible to another thread that is reading that variable's value.</div><div><br /></div><div><b>slide 10 (instance = new LoneRanger(””) != Atomic operation):</b></div><div>If you look at the example in slide 7, you might think that the statement below is an atomic statement.</div><div>instance = new LoneRanger();</div><div>But that is not the case. For the sake of simplicity this slide shows the statement above broken into 2 operations. In the first part, an instance of the class is constructed, and in the second part a reference to that instance is assigned to the variable instance.</div><div><br /></div><div><b>slide 11 (Compiler Reordering):</b></div><div>Now what if the compiler reorders the instructions in such a way that the field instance is assigned an uninitialized block of memory (created for the class LoneRanger), and then the constructor of LoneRanger is invoked in the second step. </div><div><br /></div><div><b>slide 12 (Compiler Reordering Pseudocode):</b></div><div>This slides shows pseudocode to understand the effect of compiler reordering on the <cite>double checked locking</cite> code. The code in the synchronzied block which instantiates our Singleton is broken into two steps: assignment, and initialization, where the assignment happens before the initialization.</div><div><br /></div><div>Now imagine thread T1 enters the <code>getInstance()</code> method, enters the synchronized block and executes the statement which assigns the block of memory allocated for LoneRanger to the variable called instance. If T1 gets preempted and thread T2 enters <code>getInstance()</code> then T2 may see a non null value for instance. Thus T2 will actually be returned an initialized object of LoneRanger. This could cause all sorts of bugs in the software.</div><div><br /></div><div>So in the first problem described a few slides back, we ran into the issue of having multiple instances of our Singleton, which we attempted to fix with the <cite>double checked locking</cite> idiom. However, this introduced the issue where a thread might be given a reference to an uninitialized instance of the Singleton.</div><div><br /></div><div><b>slide 13 (Can We Prevent reordering):</b></div><div>Programmers never give up :-) When an even smarter programmer was explained this problem, he remarked "so let us prevent reordering and our problem will be solved !". Ok let's try that, but how do we prevent reordering? Well there is something called a memory barrier, which may help us. Instructions cannot be reordered across memory barriers (although they may be reordered within a memory barrier). Let's see if we can introduce memory barriers to prevent the reordering that's been giving us such a hard time till now.</div><div><br /></div><div><b>slide 14 (Memory Barrier):</b></div><div>A memory barrier is a low level (at the level of the processor) construct which is used to create a fence around instructions. Instructions which are fenced inside a memory barrier cannot be moved out of the fence, and memory caches are also synched with main memory when a memory barrier is encountered.</div><div><br /></div><div><b>slide 15 (Memory Barrier):</b></div><div>This slide explains memory barriers with an illustration. In this slide notice that instructions (instr2, instr3, & instr3) are fenced with the memory barrier. Because of the semantics of a memory barrier these instructions can never be moved out of the barrier, but they may be re-ordered within the memory barrier. We can also see when the memory barrier is entered the local processor cache is invalidated and latest values are read from the main memory, and when the memory barrier is exited then the local cached is flushed and the main memory is updated with the latest values.</div><div><br /></div><div><div><b>slide 16 (Memory Barrier):</b></div><div>Because memory barrier is a low level construct, there is no way to explicitly create one in a high level language like Java. However, the synchronized keyword in Java implicitly creates a memory barrier. Before I read this, I had no clue that synchronization in Java is anything more than a mutex. But I read somewhere that when a monitor is obtained an memory barrier is also created and when a monitor is released the memory barrier ends (this is my understanding, please correct me if this is wrong).</div></div><div><br /></div><div><b>slide 17 (Double Checked Locking With Memory Barrier):</b></div><div>The fact that assignment and construction of our Singleton could be reordered created the issue of potentially having an uninitialized Singleton. We want to ensure that the reordering does not happen. For that let us separate the construction and assignment with a memory barrier and put the assignment after the construction. We do this with 2 synchronized blocks and a temporary variable. In the inner synchronized block we will initialize the Singleton and assign it to a temporary variable. We don't care if this is reordered, because the class variable instance will still be null which will prevent another thread from getting an initialized instance of the Singleton. Then we assign the reference to the temporary variable to the class variable instance. This happens outside the memory barrier. So by employing a memory barrier we are hoping to maintain program order in the execution of instructions. Again a very smart solution, but unfortunately this does not work either.</div><div><br /></div><div><b>slide 18 (Monitor Exit Semantics):</b></div><div>The semantics of monitor exit specify that everything that happened before the monitor exit should happen before it, which means that nothing from the inner synchronized block (where we instantiate the Singleton) will be moved out of the inner synchronized block, however, it does not mean that something will not be moved from outside of the block to within it.</div><div><br /></div><div><b>slide 19 (Monitor Exit Semantics):</b></div><div>This slide explains monitor exit semantics with an illustration. As we can see inst2 and inst3 are within the memory barrier. Neither of them will be moved out of the block, but inst4 which is out of the memory barrier may be moved in the barrier.</div><div><br /></div><div><b>slide 20 (Double Checked Locking With Memory Barrier):</b></div><div>This slide shows the code where we tried to use the memory barrier. But this time we show the code with a potential reordering. With the statement instance = tempInstance inside the memory barrier it could be further reordered to the point before the actual construction of the Singleton, bringing us back to the same problem.</div><div><br /></div><div><b>slide 21 (OK So What The Hell Will Work ?):</b></div><div>Alright enough of playing around... not I am getting a bit edgy.... just tell me what the hell is going to work. Is this what you are saying to yourself? Java has a special modifier called volatile. We can use these fields to help us with the Singleton.</div><div><br /></div><div><b>slide 22 (Semantics of volatile):</b></div><div>The volatile modifier is used in Java to communicate state changes between threads. This slide explains the semantics of volatile with an illustration.</div><div><br /></div><div>The code on the left shows a class which has two methods: writer() and reader(). The writer() method writes values of variables x and v to memory, and the reader() method reads values of x and v from memory. Imagine that both these method will be called by different threads T1 and T2, running on different processors P1, and P2. Each processor has a local memory cache and off course there is also the main memory. The variable v is volatile and x is not volatile. </div><div><br /></div><div>When thread T1 executes writer() we are guaranteed that the instructions will not be reordered because v is volatile. We are also guaranteed that when thread T1 exits the method, processor P1's local cache will be flushed to main memory, which means that the value of x as well as v will be visible to other threads. When thread T2 executes the method reader(), it first reads the value of v, this is going to invalidate the local cache of P1, and fetch the latest values from main memory. This ensures that it sees the latest values (which in this case were the ones written by T1 when it called writer()) of v and x.</div><div><br /></div><div>So this slide explains the semantics of volatile and how volatile may be used to ensure that instructions are executed in program order and also ensure the visibility of writes by one thread by another thread.</div><div><br /></div><div><b>slide 23 (Double Checked Locking With Volatile):</b></div><div>This slide shows our old and well known example which uses <cite>double checked locking</cite>, but this time with a little difference. This time we have made the variable instance a volatile field. Making it volatile will ensure that the write to initialize the LoneRanger object and the assignment of that instance to the field instance will not be reordered. This elimitaes the problem of seeing an uninitialized Singleton object.</div><div><br /></div><div><b>slide 24 (Singleton With Static Initializer):</b></div><div>After doing all these coding gymnastics, in this slide we show a solution which is probably the simplest solution for creating a thread safe Singleton. Instead of instantiating the Singleton in <code>getInstance()</code>, we use a static initializer, which will instantiate the Singleton when the class is loaded. Java semantics ensure us that all static fields of a class will be completely initialized before the class is available for use. This means that the field instance will be properly initialized before anyone makes use of the class to get an instance of the Singleton.</div><div><br /></div><div><b>slide 25 (Singleton With Static Initializer):</b></div><div>In this slide we understand the pros and cons of using a static initializer. Even though using a static initializer is the simplest solution, it is possible that everything the Singleton needs to initialize itself may not be available when the class is loaded (which causes the static initializer to be invoked). It is also possible that the Singleton may be eagerly loaded, which may result in greater loading time for our application, something that may be undesirable if instantiating the Singleton is an expensive operation.</div><div><br /></div><div><b>slides 26, 27, 28 (Summary):</b></div><div>In these slides we summarize the main points covered in the presentation till now.</div><div><br /></div><div><b>slide 29 (Resources):</b></div><div>Links to some very good and relevant articles, including my <a href="http://www.cs.umd.edu/~pugh/java/memoryModel/DoubleCheckedLocking.html">favorite article</a> by Bill Pugh.</div><div><br /></div><div><b>slide 30 (Thank You):</b></div><div>Thank you for your patience. I hope you found this presentation useful. One more thing before signing of - many people (<a href="http://www.c2.com/cgi/wiki?SingletonsAreEvil">here</a> and <a href="http://tech.puredanger.com/2007/07/03/pattern-hate-singleton/">here</a>, but <a href="http://mattberther.com/2004/05/27/singletons-are-not-evil">someone</a> also disagrees) consider Singletons to be evil...</div><script src="http://b.scorecardresearch.com/beacon.js?c1=7&c2=7400849&c3=1&c4=&c5=&c6="></script><script src="http://b.scorecardresearch.com/beacon.js?c1=7&c2=7400849&c3=1&c4=&c5=&c6="></script>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com3tag:blogger.com,1999:blog-7520738.post-1478120323761591882010-07-24T15:44:00.007+05:302010-07-24T19:20:19.133+05:30DIY Masters in Computer ScienceSince my formal education, a lot of advances have taken place in software development. I have been able to keep up with a few with regular reading and practice. But a lot of this learning has been a bit random, and as a result a bit dissipated as well. I feel like I want to engage in continuous learning, in a more organized manner.<br /><br />Over the years there are several core concepts which I have forgotten because I have not been able to use them in my regular work. I feel like relearning those concepts.<br /><br />I think the volume and content of both these can constitute a masters course in Computer Science. But I do not want to go back to school. Not because there is anything wrong with school - I had a great time in grad school. But here's why...<br /><br /><span style="font-style: italic;"></span><blockquote><span style="font-style: italic;">I don't want to go back to school because I want to define the courses I want to learn, and not pick up from what's offered.</span><br /></blockquote><blockquote><span style="font-style: italic;">I don't want to go back to school because I want to be able to learn at my own pace, which at times may be slower than 1 course per semester.</span><br /></blockquote><blockquote><span style="font-style: italic;">I don't want to go back to school because I do not want to spend a fortune learning stuff which I can learn myself using free resources.</span><br /></blockquote><blockquote><span style="font-style: italic;">I don't want to go back to school because I would rather create online/social credentials than get a school certificate.</span><br /></blockquote><blockquote><span style="font-style: italic;">I don't want to go back to school because I want to demonstrate that a person can not only get knowledge but also credentials if they engage in disciplined self-study and leave learning trails on the Internet.</span><br /></blockquote><br />So this time I am doing a DIY (Do-It-Yourself) masters in Computer Science. so I can refresh things I have forgotten and learn new technologies and concepts which have gained importance in recent times, in an organized way.<br /><br />I did a Masters in Computer Science more than a decade back. Since then, Internet, communication technologies, and social networking, have made it possible for someone to do a similar program all by themselves, using open courseware, and social learning.<br /><br />By doing this program, I am not only planning to enhance my own knowledge, but am also hoping to show how one can get a Master's education worth of knowledge, and credentials, by self learning, and without spending a fortune. Here's a very brief <a href="http://opencs.wikidot.com/statementofpurpose">statement of purpose</a>.<br /><br /><br /><span style="font-weight: bold;">My DIY Learning Process:</span><br /><br />I have created a <a href="http://opencs.wikidot.com/learningplan">learning plan</a> which outlines at a high level the topics I want to learn. I will study one or two topics at a time, and at a manageable pace, given other work commitments.<br /><br />Once the topics to learn have been identified, I will identify learning resources, forums, and mentors for that topic.<br /><br />A very basic study plan is to study the material, and make notes of my understanding, as well as questions and thoughts, I get in my mind as I am learning. I will make these notes available on a <a href="http://opencs.posterous.com/">special blog</a>. This <a href="http://opencs.posterous.com/">blog</a> will serve as a personal knowledge base (I can refer to it in the future), as well as a learning trail (for proof of study and understanding).<br /><br />All the homework I do while I am taking a course will be made available in the public domain. I will either post it on my <a href="http://opencs.posterous.com/">blog</a>, or if the homework involves coding, on a public open source repository such as Github. I will also do one or more projects to practice the entire body of knowledge as a whole and publish that too in the public domain.<br /><br />I will also create presentations of what I learn, and make them available in the public domain.<br /><br />I will connect with mentors who are experts in the topic I am learning. Depending on their time availability I will request them to help me identify gaps in my understanding, and validate my knowledge.<br /><br />When I have doubts, I will ask questions on Internet forums. If my questions are not answered satisfactorily on the forums, I will refer them to my mentors.<br /><br />Please visit my <a href="http://opencs.wikidot.com/learningplan">learning plan</a> for further details.<br /><br /><br /><span style="font-weight: bold;">Establishing Credentials:</span><br /><br />A person can have several reasons for learning. One is for the knowledge (either for the joy of knowing something, or for more practical application of the knowledge), and another for establishing credentials, so someone else may entrust us with work which requires such knowledge. A self learned person may have the knowledge, but may lack credentials to prove it. It is also possible for a person studying in a silo to think he has grokked what he just learned, when in reality he may not have understood the matter properly. To be able to provide proof of knowledge as well as to validate my learning with other practitioners, I plan to engage in what can be loosely classified as social learning.<br /><br />I will do the following to document my learning and to engage with the community of practitioners, in the hope of validating my knowledge and establishing credentials for what I learn:<br /><ul><li>Answer questions on forums</li><li>Blog my study notes, and clearly articulate my takeaway from all the lectures I view, or text I read</li><li>Create presentations and post them on YOUTube, or other video sharing services</li><li>Publish homework on open source code repositories such as GitHub, etc</li><li>Request my mentors to quiz me to help me find gaps in my understanding of a topic. I will publish the quiz as audio/video and request the mentor to post their feedback in the public domain</li><li>Take quizzes and tests wherever possible and economical<br /></li></ul>So I am leaving these learning crumbs on various places on the Internet, but I need something to bring everything together. Something which can serve as the focal point, or a lens into all my learning. I created a <a href="http://opencs.wikidot.com/">wiki</a> site to serve as the focal point.<br /><br />Have you been meaning to learn something yourself? Perhaps you can do your own DIY course in whatever interests you. Here is a lens into my <a href="http://opencs.wikidot.com/">DIY experiment</a>.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com2tag:blogger.com,1999:blog-7520738.post-71597277457658521842010-05-12T17:14:00.000+05:302010-05-12T17:14:00.386+05:30Android apps can run in parrallel (video)This is the seventh in a series of videos published by Google on Android programming.<br /><br /><object width="480" height="385"><param name="movie" value="http://www.youtube.com/v/7lScgyXGxwo&hl=en_US&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/7lScgyXGxwo&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="480" height="385"></embed></object><br /><br />In this video the speaker starts an app to track photos his buddy publishes on Flickr. He can keep this application running in the background, so while he is browsing or checking his email, this application will constantly track the photos and notify him if a new photo has been uploaded.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com3tag:blogger.com,1999:blog-7520738.post-77745557088315532832010-05-11T16:44:00.001+05:302010-05-11T16:44:00.881+05:30Adndroid apps don't have any borders (video)This is the sixth in a series of videos provided by Google on Android programming.<br /><br /><object width="480" height="385"><param name="movie" value="http://www.youtube.com/v/3LkNlTNHZzE&hl=en_US&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/3LkNlTNHZzE&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="480" height="385"></embed></object><br /><br />Index:<br />00:00 Introduction<br />00:32 Zebra crossing application<br />01:35 Library app<br />02:14 A GeoSocial app which combines user GPS, user created photos, and Compass<br /><br /><br /><span style="font-weight:bold;">My Takeaway:</span><br />Android applications do not have any borders. They can use data from other applicatiosns, they can use hardware available on the device such as camera, compass, GPS, accelerometer, etc, and they can also use content from the web API's.<br /><br />The first application called Zebra Crossing is an application which can pull information from bar codes and QR codes. So if you photograph a product's bar code and give it to the application, it will pull up information about the book from the web. If on the other hand you give it a QR code from the back of a business card, it can extract contact information about that person which you can use to call or send email. The Zebra Crossing app also publishes intents, to allow other applications to communicate with it.<br /><br />The second application is a library application which uses the "Zebra Crossing" app to add books to your personal library.<br /><br />The third application, which I found to e really cool is an application which mashes together GPS, photographs, and the Compass to create a GeoSocial application. So here's what it does. Imagine you are on a vacation and want to locate cool things around where you are. You can use this application to find out all the photographs people have taken around that locality. If you find something you like, you can actually locate that thing (which was photographed) on a map and also use the Compass to get there. Cool isn't it?Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-56587188017326100512010-05-10T10:05:00.001+05:302010-05-10T10:05:00.153+05:30How to embed the web in Android apps (video)This is the fifth in a series of videos provided by Google on Android programming.<br /><br /><object width="480" height="385"><param name="movie" value="http://www.youtube.com/v/Ex7YsQ_YH2U&hl=en_US&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/Ex7YsQ_YH2U&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="480" height="385"></embed></object><br /><br />This video shows how we can use the WebView to create applications that render HTML pages. Along with being able to embed HTML and Javascript web pages in apps, the most exciting thing I found in this view was the fact that the Javascript in a webpage can communicate with Java code and Java code can communicate with javascript. This is really cool.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com4tag:blogger.com,1999:blog-7520738.post-29507065426456649692010-05-09T13:06:00.000+05:302010-05-09T13:06:42.493+05:30Android programming - All applications are created equal (video)This is the fourth video in the series of videos provided by Google on Android programming.<br /><br /><br /><object width="480" height="385"><param name="movie" value="http://www.youtube.com/v/3aUjukCdPyQ&hl=en_US&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/3aUjukCdPyQ&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="480" height="385"></embed></object><br /><br /><br /><span style="font-weight: bold;">Index:</span><br />00:25 Dianes ringtone app<br />01:08 App to create a shortcut to anything on the system<br />01:36 Replacing the home screen (End at 02:17)<br /><br /><span style="font-weight: bold;">My Takeaway:</span><br />This video shows that all applications created on the Android platform are equal. Even though I have not done any iPhone development, I believe applications written for iPhone do not have access to everything the way Android applications do. So this is a positive for Android development.<br /><br />In this video we see how to a custom application can change the ringtone on an Android phone, how another application can create shortcuts to anything on the phone, and how we can also change the 'Home' application.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-47106393784644854712010-05-08T12:45:00.003+05:302010-05-08T15:48:17.865+05:30Android Programming - API's (Video)This is the third video in the series of videos provided by Google on Android programming.<br /><br /><object width="480" height="385"><param name="movie" value="http://www.youtube.com/v/MPukbH6D-lY&hl=en_US&fs=1&"></param><param name="allowFullScreen" value="true"></param><param name="allowscriptaccess" value="always"></param><embed src="http://www.youtube.com/v/MPukbH6D-lY&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" width="480" height="385"></embed></object><br /><br /><span style="font-weight:bold;">Index:</span><br />00:00 Introduction<br />00:16 Android API's<br />00:24 Location Manager<br />01:25 XMPP<br />02:42 Notification Manager<br />04:08 View System<br />06:00 Conclusion (Ends at 07:05)<br /><br /><span style="font-weight:bold;">My Takeaway:</span><br />In this video the speaker talks about API's provided on the Android platform to developers.<br /><br />The <span style="font-style:italic;">LocationManager</span> API allows an application to get the location of the device it is running on. This information can be used to register intents, which will inform the user if they are close to an interesting location such as a Ice Cream shop. I can also think of another use. If traffic information is available, then we can also use the location manager to inform us if we are getting close to a high traffic area. Interestingly this API uses whatever information it has to determine the location. If GPS information is available then it will use that, otherwise it will use cell tower information.<br /><br /><span style="font-style:italic;">XMPP Service</span> is used to send messages to a device. It can be used to send device to device messages, or server to device messages. I think this API can have very interesting uses. It can be used for multiplayer games, and it can probably also be used by trekkers to track each other.<br /><br />The <span style="font-style:italic;">Notification Manager</span> API provides applications the ability to send notifications to the user on the status bar. My impression is that this API is very well designed. The notification appears on the status bar, such that if a user selects it (using whatever input method available... touch, etc), it will display a preview about the application and notification. If the user is interested, they can further select the notification to go to the application which send it.<br /><br />The <span style="font-style:italic;">View system</span> provides several view controls help developers make their applications. Interesting controls include a Map control to embed location information in applications, and an HTML control to embed web pages in applications.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-63182611066358761262010-05-05T20:41:00.004+05:302010-05-17T22:34:11.958+05:30Android programming - Application lifecycle (Video)This is the second video in the series of videos provided by Google on Android programming.<br /><br /><object height="385" width="480"><param name="movie" value="http://www.youtube.com/v/fL6gSd4ugSI&hl=en_US&fs=1&"><param name="allowFullScreen" value="true"><param name="allowscriptaccess" value="always"><embed src="http://www.youtube.com/v/fL6gSd4ugSI&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" height="385" width="480"></embed></object><br /><br /><br /><span style="font-weight: bold;">Index</span><br />00:00 - Introduction<br />01:00 - How Android integrates apps written by different authors.<br />07:50 - Conclusion (Ends at 08:16)<br /><br /><br />This video walks us through a hypothetical use case, where a user opens their email, reads a message which contains a link to some location. The user then clicks on the link, opens the browser and views the location on Google Maps.<br /><br />While engaging in these activities, the user starts various applications (processes) and also navigates back and forth among them. The video explains how Android manages resources and the application stack so the user can navigate across their apps seamlessly.<br /><br /><span style="font-weight: bold;">My Takeaway</span><br />From the video it seems like Android supports a maximum of 4 running processes. One of those processes is the System process, so a user can have at most 3 applications running simultaneously. However, this does not mean that a user cannot open more applications. When the user opens the 4th application, Android will automatically terminate an application, and will also revive it in a known state if the user were to go to it again.<br /><br /><span style="font-weight: bold;">Update:</span><br /><a href="http://ram.redanyway.com/">Ram</a> pointed out that "4 running processes" is purely a number they used in this example. He is absolutely correct. 4 is just an example (perhaps they assumed 64 MB RAM on the phone...). The real number depends on the amount of memory (RAM) available on the phone.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com2tag:blogger.com,1999:blog-7520738.post-76847389094941213262010-05-02T12:20:00.007+05:302010-05-03T20:24:32.707+05:30Android programming - architecture videoI have been getting interested in Android programming, so I went over to their website and found some introductory videos.<br /><br />Here's the first one with a little index of what is discussed and my take away from the video.<br /><br /><object height="385" width="480"><param name="movie" value="http://www.youtube.com/v/QBGfUs9mQYY&hl=en_US&fs=1&"><param name="allowFullScreen" value="true"><param name="allowscriptaccess" value="always"><embed src="http://www.youtube.com/v/QBGfUs9mQYY&hl=en_US&fs=1&" type="application/x-shockwave-flash" allowscriptaccess="always" allowfullscreen="true" height="385" width="480"></embed></object><br /><br /><span style="font-weight: bold;">Video Index:</span><br />00:0 Introduction<br />00:40 Linux Kernel<br />01:09 Native Libraries<br />03:09 Android runtime<br />04:13 Core libraries<br />04:31 Application framework<br />07:00 Applications<br />07:25 Application building blocks<br />09:37 Example of re-using components in Android<br />12:18 Conclusion and resources<br />12:48 End<br /><br /><span style="font-weight: bold;">My Takeaway:</span><br /><br />Architecture wise the Android platform has several layers:<br /><ol><li>Linux Kernel</li><li>Native Libraries</li><li>Android Runtime</li><li>Core Libraries</li><li>Application Framework</li></ol>The applications that we make are build on top of the "application framework" layer.<br /><br />The Linux Kernel was chosen because of it's stability, services, security, and presence of several device drivers.<br /><br />Native Libraries consist of various components for rendering graphics and fonts (Surface Manager, OpenGL, SGL, Freetype), a lightweight database engine (SQLLite), a browser engine (WebKit), and others.<br /><br />The Android Runtime consists of Dalvik the Java Virtual Machine created by Google, which is optimized for running on embedded devices which have low resources. Dalvik runs *.dex files which are created by converting *.jar and *.class files. On top of Dalvik are the core Java libraries consisting of things like the Collections, IO API, etc.<br /><br />Then the Core libraries layer consists of components such as Activity Manager, Resource Manager, Package Manager, Content Provider, Telephony Manager, XMPP, etc.<br /><br />Android applications typically have 4 building blocks, which applications mayor may not use. These are:<br /><ol><li>Activities</li><li>Intent Receivers<br /></li><li>Services</li><li>Content Providers</li></ol>The video ends with an example of how various applications can re-use a photo picker component. So, we may have multiple applications like email, Blooger, etc which may need to select a photo. These applications do not have to write their own photo picker. They just show an "Intent" to pick a photo, and the component which fulfills that intent will be chosen. This binding is done pretty late, so we can actually change the component that fulfills the intent, and then henceforth that component will be used for that intent.<br /><br />In the next few blog posts I will be embedding more Android videos along with my learnings.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com1tag:blogger.com,1999:blog-7520738.post-80528305136843128242010-04-30T16:32:00.002+05:302010-04-30T16:47:47.886+05:30tightvnc with gnome messes up the keyboard mappingEverytime I run our unit tests, I get Java Swing windows flying across my screen making it impossible to work. A friend suggested that if I ran the tests in a vncclient session, the windows will be contained within vncviewers window.<br /><br />So I installed tightvncserver and client on my Ubuntu 9.10 machine. When I started vncviewer I realized that the keyboard mapping as messed up, making it impossible to type anything sensibly in the vnc session.<br /><br />Some searching seems to suggest that Gnome is causing this problem. <a href="http://https://bugs.launchpad.net/ubuntu/+source/vino/+bug/112955">This page</a> offered a solution of changing VNC's startup file to not fully start Gnome, and it worked for me.<br /><br /><p>Workaround: I modified my ~/.vnc/xstartup to be:</p> <p>#!/bin/sh</p> <p>xrdb $HOME/.Xresources<br />gnome-wm &<br />gnome-panel &<br />nautilus --no-default-window &<br />gnome-cups-icon &<br />gnome-volume-<wbr>manager &<br />xterm &</p>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-39847360720662750842010-04-27T10:47:00.003+05:302010-04-27T10:57:35.888+05:30Java Applet on 64 bit LinuxI have been working on an Ubuntu 9.10 (64 bit system) from some time. I had read some stories of problems running 64 bit Java Applets on 64 bit Firefox, so when I needed to use Applets I did some googling to figure out how to do it.<br /><br />I came across a couple of posts. Some had different solutions for different versions (3.5, 3.6) of Firefox, and they also wanted me to use IcedTea. The solution I used is outlined <a href="http://ubuntuforums.org/showthread.php?t=1013658">here</a>, and it worked perfectly well for me.<br /><br />Note: You may not have libnpj2.so in the same place mentioned below.<br /><br /><pre class="alt2" dir="ltr" style="border: 1px inset ; margin: 0px; padding: 6px; overflow: auto; width: 640px; height: 50px; text-align: left;">mkdir ~/.mozilla/plugins/<br />ln -s /usr/lib/jvm/jre1.6.0_12/lib/amd64/libnpjp2.so ~/.mozilla/plugins/</pre>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com0tag:blogger.com,1999:blog-7520738.post-46283731942449959492010-04-06T22:07:00.007+05:302010-04-16T14:21:13.561+05:30Showing lines before and after a grep matchToday I ran running grep on the output of <code>hg log</code>, but only to realize that I wanted a couple of lines before and after the line which matched as well.<br /><br />I am sure this is common knowledge, but I did not know how to do it, so am sharing it in the hope that someone finds it useful.<br /><br /><pre class="adaptiveconsole"><br />hg log | grep --before-context=2 --after-context=2 username<br /></pre><br /><br />Running the above showed me changeset number, comments etc for all the mercurial changesets committed by the specified user.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com2tag:blogger.com,1999:blog-7520738.post-58509572754969242842009-10-04T09:55:00.004+05:302009-10-13T11:31:12.425+05:30Some thoughts on redesigning educationSome time back I read a <a href="http://www.geekybusiness.com/redesigning-education">blog post</a> on redesigning education. It asked some very good questions. Stuff which I had been thinking of myself. I left my thoughts on the blog, but I would also like to start a conversation around these ideas with those who read this blog as well.<br /><br />I would like to know what other people think of the issue of redesigning (college) education.<br /><p>I have often thought about how college education can be improved. To answer this question, we first have to ask a very basic question. What is the purpose of education?</p><p>To me, we need education for 3 things:<br /></p><ol><li>To learn more about the world around us</li><li>To lead positive constructive lives</li><li>To earn a good living / fulfill our ambitions</li></ol><p>I think education has to a large extent evolved to fulfill #3 (with a bias towards earning a comfortable living). The semester system, along with multiple choice tests, and grading, has made our education system into an assembly line. Students are pushed into the assembly line, given classes, administered tests, branded with a grade and pushed out of the assembly line, into the workforce.</p><p>Even though this is not the best way to teach, this system has for the most part worked till now. I think there are several reasons.</p><p>1. For many of students, getting an education is simply a means to gain employable skills (I do not say this in a negative way).<br />2. A university has to provide these skills in a time and cost efficient way to the students. It has to provide some branding which will be valuable to students, and make it easy for employers to spot the talent they want to recruit.</p><p>In the last few years I have taught programming classes at a local college. In one semester, I tried to move away from the regular grading mechanism. I wanted to focus on deep learning of programming skills, sharing and brainstorming ideas, code reviews, collaborating with the community of practice, etc. However, students still needed to be graded, so I had to come up with a way to fulfill that requirement also. Without going into details I will simply say, in that semester, I put in an effort which was orders of magnitude greater than the regular effort (because I had to fulfill the grading requirement). Students learned a lot in that semester, and I too enjoyed running that course, but towards the end of the semester, I was tremendously stressed out managing the course, and my regular programming work.<br /></p><p>So even though the current education system is sub-optimal, I do not think it is because of evil intentions. It is possibly the most practical mechanism that has emerged over time.</p><p>However, many things have changed in the past few decades. The shelf life of knowledge has greatly reduced. The Internet has made it possible to share information, and collaborate with people at a distance. Many businesses have started valuing knowledge over degrees (this is at least true in software, and probably in media, advertising, etc as well). The read-write web has made it possible for students to easily create a digital portfolio, and to establish alternate credentials. So all the things a student needs for learning (information, interactions, guidance, review and feedback, and credentials) can be put together in a non traditional way. I stress so much on non traditional because the traditional education system excludes many learners, and this I feel can be changed.<br /></p><p>So here is the ideal education system according to me:</p><p>A student enters the education system with some goals, and connects with mentors who will help her in fulfilling those goals. These mentors may be traditional teachers who work for a university, or may be employees of an organization, senior practitioners who choose to help on the Internet, friends, family, or people who have retired from the workforce, but would like to share their wisdom and help others. </p><p>With the help of mentors, the student defines learning goals, and identifies resources. These resources could be traditional classes, books, or digital material (videos, text, audio...). </p><p>With these materials and a micro mentor network, the student begins her learning process. When they have questions, there are a several resources from their mentor network they can turn to. These students may be part of a traditional classroom in some cases, whereas in other cases they may be part of a local or virtual study group. Think of it as being part of an appropriate group for every course they want to take. There are several tools, both real world as well as digital to enable this.</p><p>As the student learns, they leave a digital learning trail. One possible way is using blogs, audio recordings, wikis, contributions on forums, and other digital artifacts. So students blog their assignments and problem sets. They participate on Internet forums asking and answering questions. They may create a podcast (or screencasts) of their assignments and presentations. Maybe some students will be able to do practical work which is similar in nature to the assignments and problem sets.</p><p>Senior practitioners, traditional teachers, mentors from the community, help the student understand the strengths and weaknesses in their knowledge. The student subsequently fills in the holes by seeking help from their mentor network, and by revisiting those concepts. Community members endorse a students' understanding of their topic of study. Maybe tests still have a place... I don't know...</p><p>When a student knows enough, they can enter the workforce. Proof of their knowledge already exists on the Internet. Some organizations may accept them purely based on their digital portfolio and an interview, while others may expect them to take some tests. Students can prepare for these tests, if they wish to work for that organization.</p><p>Students however, do not stop their education after getting employed. The process outlined above continues, but perhaps at a slower pace. Thus even after starting work a person continues to accumulate (non credit) credentials. These credentials may either be continuing education certificates from a university or Internet endorsements from the community of practice.<br /></p><p>This to me is the ideal educational scenario. But it will not be without problems. </p><p>There will always be the issue of credibility of an online portfolio, and endorsements from random mentors. Is there a process using which we can streamline online credentials and validate the credibility???<br /></p><p>There will be issues with self-discipline. College gives a certain structure. Doing it by oneself needs a lot of will-power and discipline. One can easily while away time, thinking they are learning something. Maybe the <a href="http://www.pomodorotechnique.com/">Pomodoro technique</a> can help here.<br /></p><p>But I think this scenario is workable. I like it because it allows students to learn at their own pace (without excluding students who do not have resources to attend traditional colleges), from many mentors, thus gaining knowledge and wisdom from many sources. But most importantly, it allows students to take control of their education, and seek out the best, albeit disparate sources for knowledge.<br /></p><p>Here's my own humble effort towards contributing towards this goal - <a href="http://www.adaptivelearningonline.net/" rel="nofollow">http://www.adaptivelearningonline.net</a></p>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com7tag:blogger.com,1999:blog-7520738.post-73260516995251026822009-08-24T22:38:00.003+05:302009-08-24T22:50:27.651+05:30Fixing a mistake after commiting in GitSo, I ran into an interesting issue while coding today. I made a lot of changes and committed code to my Git repository. Just after committing, I realized that I still had to make some changes to a file and those changes should also have gone in with the previous commit.<br /><br />Fixing a commit mistake can be done in two ways. Revert the commit, make the changes and then recommit them. This is the preferred way if we have already made the changes public (and thus someone may already have pulled them). However, in my case I am the only one working on this project right now and I had not pushed the changes to GitHub, so I could try the other method.<br /><br />So here's what I did. I made changes to the file, added it to the index, and committed it thus:<br /><pre class="adaptiveconsole"><br />$git commit --amend<br /></pre><br /><br />Committing code with the --amend switch will cause the index to be committed as part of the previous commit. Git also brings up the editor window, in case we want to change the commit message. This method can also be used to change the commit message without adding any files to the commit.<br /><br /><span style="font-weight: bold;">Reference: </span><br /><ul><li><a href="http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#reverting-a-commit">Git documentation on kernel.org</a><br /></li></ul>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com1tag:blogger.com,1999:blog-7520738.post-571061538520541942009-08-23T17:56:00.006+05:302009-08-23T22:57:50.859+05:30Lack of design patterns in PythonWhile searching for PyCon videos, I came across <a href="http://bitworking.org/news/">Joe Gregorio's</a> very good video on (lack of) design patterns in Python. I have also added the video timeline along with some notes I made for myself and my takeaway. Enjoy the video.<br /><br /><embed src="http://blip.tv/play/g4Vi_9ZkAg" type="application/x-shockwave-flash" width="480" height="350" allowscriptaccess="always" allowfullscreen="true"></embed> <br /><br /><p><br /><strong>Timeline:</strong><br />[00:00] - Start<br />[00:15] - People pick tools based on a mythology and not necessarily facts<br />[02:35] - Python isn't just Java without the compiler<br />[03:34] - Design patterns are also a sign of weakness in a language<br />[04:06] - Lack of design patterns in Python (proof of lack)<br />[06:10] - Patterns are built into Python<br />[07:00] - Strategy pattern in Python the wrong and right way<br />[07:36] - The strategy pattern is invisible in languages with first-class functions<br />[08:07] - Some other language features in Python (first class functions, metaprogramming, iterators, closures)<br />[09:17] - The iterator pattern (iterators) is also built into Python<br />[09:36] - The observer pattern is also built into Python<br />[10:17] - Factory method pattern in Python (<br />[10:34] - Abstract Factory Pattern<br />[10:40] - Strategy pattern goes away becaise of first class functions<br />[11:08] - Drawing some useful conslusions<br />[12:20] - Drawing light on Python from the perspective of patterns<br />[12:31] - Thread Pool and Concurrency patterns (should we be talking about language features in Python for concurrency patterns???)<br />[13:49] - Channels (a model for concurrent processes)<br />[15:12] - PyCSP (implmentation of csp on top of Python)<br />[18:42] - Conclusions, summary, and questions<br />[19:17] - end (video goes on for a few more seconds waiting for questions)<br /></p><br /><p><br /><strong>Notes:</strong><br />There are very few references to design patterns in Python mailing lists and discussions around Python... design patterns could be a sign of weakness in a language... patterns are built into Python (hence very little discussion)...strategy pattern is invisible in languages with first class functions...<br /></p><br /><p><br /><strong>Takeaway:</strong><br />If you have to implement a design pattern, first look at language features and try to determine if any can be used instead of the pattern or at least assist in the implementation of the pattern while programming in that language.<br /><br />Ask yourself if a language feature would make that pattern part of the language itself.<br /><br />Concurrency patterns are a rich area to look at.<br /></p><br /><p><br /><strong>References:</strong><br /><ul><br /><li><a href="http://bitworking.org/news/Python_isnt_Java_without_the_compile">Python isn’t just Java without the compile</a></li><br /><li><a href="http://norvig.com/design-patterns/">Design patterns in dynamic programming</a></li><br /><li><a href="">Advanced topics in programming languages: Concurrency and message passing in Newspeak (Rob Pike)</a></li><br /><li><a href="http://home.comcast.net/~refilman/text/dpl/csp.pdf">Channels (pdf)</a> C.A.R.Hoare</li><br /></ul><br /></p>Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com3tag:blogger.com,1999:blog-7520738.post-1706874616363799492009-08-17T22:32:00.001+05:302009-08-17T22:33:57.414+05:30iAcceleratoriAccelerator<br /><br />I took a sabbatical from my consulting work this summer to participate in the <a href="http://www.iaccelerator.org/">iAccelerator</a> program. This is a program for early stage software startups, similar to <a href="http://www.ycombinator.com/">YCombinator</a>, but the first of it's kind (I believe) in India.<br /><br />I enjoy teaching programming, I have taught programming classes at a <a href="http://www.scit.edu/">college</a>, done corporate workshops, and more recently have been working on a <a href="http://www.adaptivelearningonline.net/">website for participatory learning</a>. This time I was looking for a different kind of mentoring experience, something which would be free form and fun. After a discussion with <a href="http://wheresfreeman.blogspot.com/">Freeman</a>, I decided to go spend the summer at iAccelerator.<br /><br />In the first few days of the program we had introductions by all the teams where they spoke about their product and vision. This was followed by a session on team building and thinking out of the box, a few legal sessions, sessions on accounting and company law, and several other mentoring sessions. All this is very useful for early stage software stratups, especially when they are founded by techies who are excelent hackers but need some help with legal and business stuff.<br /><br />iAccelerator had ten very motivated and talented teams. I split my time helping them with technical stuff and working on my participatory learning project.<br /><br />We worked out of a large hall, converted very tastefully into a working area. Each team had their own space towards the walls, and the centre was furnished with couches, projector, a large whiteboard (where we had presentations and brainstorming sessions) and a wii for fun and entertainment.<br /><br />Even though everyone had their own work areas, many people chose to work on the couches. Working from the couches was a lot more fun and it gave opportunities for discussions, knowledge exchange, and friendly bantering. The couch culture (as I call this) in retrospect has been a very important part of the cameredierie and the excellent environment we had among us.<br /><br />A good, positive, and helpful environment is one of the best things in such a program. Whenever anyone was stuck with a problem, or needed help with something new, they would always find someone who had that knowledge and was willing to share it. Everyone had their unique strengths, and collectively we all had a lot of talent which flowed freely. Entrepreneurship is also often a journey of highs and lows. There are times when you feel like your product will take over the world, and then there are times which can be described as not so pleasant. Being in a good environment with friends, means that you are not in this alone. If someone is down he can be sure that his buddies will pull him up.<br /><br />One team found their first few customers within the group itself, and another team made a kick-ass software for internal communication which had passionate users from day one.<br /><br />Ever so often we would have mentors, and successful entrepreneurs come talk to us about various things related to business and startups. Many guests spoke about their journey as entrepreneurs, their successes, failures, and lessons learned. Besides these sessions, we were also invited for many talks given by various mentors to the IIM students. This was a benefit of being on the IIM-A campus. Several mentors also worked one on one with the teams to help them with their vision and business plans.<br /><br />Since we all had technical skills, internally we did several TechTalks on topics such as security, Amazon EC2 & cloud computing, designing with GIMP, JQuery, version control with SVN and Git, and many more. Sometimes we played tech videos from the Internet and had discussions around them. These sessions were a lot of fun and we all learned from them.<br /><br />Since Freeman has successfully created and exited a startup in the past, he had many insights about how to run a startup. He shared his knowledge and insights with everyone, helping with business plans, vision, fund raising pitches, and many other nitty gritties of creating startups.<br /><br />However, it was not just work all the time. We had a great time watching MTV while eating breakfast in the college mess. I can now tell you that watching MTV is far better than reading the morning newspaper. We played ping pong (Freeman and me had some really fun and intense ping pong sessions) ... we played cricket... on weekends we watched movies on the office projector. We also had a lot of diverse talent in the group. <a title="Jeevan Ram" href="http://twitter.com/jeevanram" id="j7hv">Jeevan Ram</a> rocked everyone with his dancing and <a href="http://www.twitter.com/ghazalravi">Ghazal</a> made us laugh with his mimicry.<br /><br />It's amazing how well we all got to know each other in just a few months. Thinking back, this was the best time I have had after graduating. Most importantly, I cannot stress enough the fact that I made really good friends, and I am very grateful for the wonderful time we all spent together.<br /><br />This year's iA program will end in a few weeks. I wish all the teams lot of success and good luck.Paraghttp://www.blogger.com/profile/16885449156962300704noreply@blogger.com5