Thursday, October 21, 2010
Wednesday, October 20, 2010
API Documentation Mistakes and How to Avoid Them
Treat API documentation as User Interface for developers who will develop and extend your application/product beyond your imagination. Good API documentation is first step of making your API popular.
Mistake #1: Developer doubles up as documentation writer
The Mistake and Misconception
Developer, the creator knows about the system the best, so she can write the best documentation. More over API documentation is targeted to developers’; they understand each other’s lingo and mindset.
The Truth
Certainly developer the creator knows the best but most of the time her sight is myopic due to limited understanding of whole system. Moreover developers are not got in natural language due to their engineering background (no offence to engineers and developers. I am a proud engineer and developer). And lastly, developers are too near to system. What is obvious to them may not be so simple and straight forward to a greenhorn or outsider.
The Solution
Get a good technical writer.
Mistake #2.: A typical technical writer writes the documentation
The Mistake and Misconception
A typical technical writer is good at writing about user interface which targets non technical users. API documentation writer should be skilled to explain from developers’ perspective.
The Truth
Sometimes you will find technical writers who have dabbled in programming. This is a big improvement to working with those who haven't, because they will at least have an understanding of the concepts of programming. But what they won't have is an understanding of how a commercial software developer thinks. How do developers get started learning something new? How do they use prototyping and architectural design? How do they debug their code?
The Solution
Get a technical writer who can code (certainly not on regular basis) or at least have done coding in past.
Mistake #3: Focusing on How and forgetting Why
The Mistake and Misconception
Most of the documentation put emphasis on How to use an API but ignore Why.
The Truth
Sometime this avoidance is purposefully but most of time this is due to lack of attention. Just remember that if documentation does not answer Why, they may end up using API in wrong way and API may become unpopular among developer community.
The Solution
With How, answer Why as well and explain under what scenario what to use, How, and Why.
Mistake #4: Not providing enough help for Getting Started
The Mistake, Misconception, and Truth
In most of API documentation, certain level of maturity of developer is assumed but never stated. This lead to lot of confusion and un-popularity of API..
The Solution
Provide multiple levels of documentation. One targeted to newbie and one at advanced developers. Also state the assumptions very clearly.
Provide simple tutorials and sample codes. Strive for sample applications which use the best practices of API.
Mistake #5: Sketchy sample code
The Mistake, Misconception and Truth
For a technical writer it is very tempting to be descriptive about API.
The Solution
Certainly descriptive text is important and helpful but just remembers that developers like to learn by doing not only by reading. Pair up Technical Writer and developer if needed to develop sample code and sample applications.
Sample code should consider:
1. Relevant information should be grouped together
2. Clarity is more important than efficiency
3. Simplicity is one of the most important factor
4. Completeness of code
5. Avoid unnecessary details ( for example use hardcoded values instead of parametrization)
6. Comment the code
7. Use sensible nomenclature
Mistake #1: Developer doubles up as documentation writer
The Mistake and Misconception
Developer, the creator knows about the system the best, so she can write the best documentation. More over API documentation is targeted to developers’; they understand each other’s lingo and mindset.
The Truth
Certainly developer the creator knows the best but most of the time her sight is myopic due to limited understanding of whole system. Moreover developers are not got in natural language due to their engineering background (no offence to engineers and developers. I am a proud engineer and developer). And lastly, developers are too near to system. What is obvious to them may not be so simple and straight forward to a greenhorn or outsider.
The Solution
Get a good technical writer.
Mistake #2.: A typical technical writer writes the documentation
The Mistake and Misconception
A typical technical writer is good at writing about user interface which targets non technical users. API documentation writer should be skilled to explain from developers’ perspective.
The Truth
Sometimes you will find technical writers who have dabbled in programming. This is a big improvement to working with those who haven't, because they will at least have an understanding of the concepts of programming. But what they won't have is an understanding of how a commercial software developer thinks. How do developers get started learning something new? How do they use prototyping and architectural design? How do they debug their code?
The Solution
Get a technical writer who can code (certainly not on regular basis) or at least have done coding in past.
Mistake #3: Focusing on How and forgetting Why
The Mistake and Misconception
Most of the documentation put emphasis on How to use an API but ignore Why.
The Truth
Sometime this avoidance is purposefully but most of time this is due to lack of attention. Just remember that if documentation does not answer Why, they may end up using API in wrong way and API may become unpopular among developer community.
The Solution
With How, answer Why as well and explain under what scenario what to use, How, and Why.
Mistake #4: Not providing enough help for Getting Started
The Mistake, Misconception, and Truth
In most of API documentation, certain level of maturity of developer is assumed but never stated. This lead to lot of confusion and un-popularity of API..
The Solution
Provide multiple levels of documentation. One targeted to newbie and one at advanced developers. Also state the assumptions very clearly.
Provide simple tutorials and sample codes. Strive for sample applications which use the best practices of API.
Mistake #5: Sketchy sample code
The Mistake, Misconception and Truth
For a technical writer it is very tempting to be descriptive about API.
The Solution
Certainly descriptive text is important and helpful but just remembers that developers like to learn by doing not only by reading. Pair up Technical Writer and developer if needed to develop sample code and sample applications.
Sample code should consider:
1. Relevant information should be grouped together
2. Clarity is more important than efficiency
3. Simplicity is one of the most important factor
4. Completeness of code
5. Avoid unnecessary details ( for example use hardcoded values instead of parametrization)
6. Comment the code
7. Use sensible nomenclature
Tuesday, October 19, 2010
Software Product Life Cycle
There is vast amount of literature on Software Development Life Cycle (SDLC) but hardly any on Software Product Life Cycle. Event with invent of Product Life Cycle (PLC) systems, focus is on non Software product.
From my experience, I have tried to depict Software Product Life Cycle in following picture:
This picture tries to depict only one product. This does not cater to product family concept directly. Using two life cycle approach, one can support product family as well with depicted Software Product Lifecycle.
From my experience, I have tried to depict Software Product Life Cycle in following picture:
This picture tries to depict only one product. This does not cater to product family concept directly. Using two life cycle approach, one can support product family as well with depicted Software Product Lifecycle.
Monday, October 18, 2010
Contemporary non function requirements of a Software Product
Version 2 of this article is posted at: http://architecture-soa-bpm-eai.blogspot.com/2011/06/contemporary-non-function-requirements.html
In any software product one has functional and non-functional requirements. It is always easier (is it so?) to identify and define functional requirements. But not so easy to define non functional. With increasing experience of software development communities, traditional non functional requirements like availability, usability, robustness (http://en.wikipedia.org/wiki/Non-functional_requirement) becoming commodity. But with changing business and technological landscape, new set of non functional requirements are emerging.
1. Open API ( synchronous and/or asynchronous)
a. Remote Object
b. Service (for example)
i. SOAP based Web Service
ii. REST Based Web Service
iii. JSON based web service
2. Multiple Channel Access (for example)
a. Connected Desktop (web browser)
b. Disconnected Desktop
c. Mobile application
d. RSS/Atom
e. WAP
f. Mobile browser
3. 3rd party/partners can build on your platform/product
4. Product as vehicle for 3rd party content
5. User as editor of relevant content
6. Content is made available to user when it is ready (push mechanism or at least reactive alert)
7. User add ancillary data ( like rating, reviews, ranking, link submission, recommendations, etc)
8. Settings/configurations can be exported and imported
9. Allow product to run as slave as well as master while integrating with other applications
10. User as owner of identity
a. Published Privacy policy with some control to end users
b. Authentication and authorization using industry wide acceptable standards ( like OpenID, facebook Id, google ID, Yahoo ID, etc)
11. Variable licensing options (for example)
a. Transaction based
b. Revenue sharing
c. User based
d. Fixed onetime cost
e. Time based
f. Cloud compliant
g. Processor based
h. Virtualization compliant
12. Social Networking features
13. Serving high band width as well as low band width environment
14. Information and data search capability
15. Domain Specific language
16. Framework for customization
17. Support distributive SDLC with multiple out sourcing partners
18. Hardware independence
19. Place for online advertisement ( like google ad)
20. Open to migrate to cloud or to non cloud deployment
21. User Analytics
22. Dash board
a. Users
b. Administrators
c. Maintenance and support staff
23. Hooks to monitoring tools
24. Early release and flexible design & architecture to modify
25. Concepts of Roles and Permissions (Identity Management)
26. Multiple Browser compatibility
Reference
1. http://en.wikipedia.org/wiki/Non-functional_requirement
2. http://en.wikipedia.org/wiki/List_of_system_quality_attributes
3. http://broadcast.oreilly.com/2010/02/nonfunctional-requirements-how.html
4. http://en.wikipedia.org/wiki/Requirements_analysis
5. http://en.wikipedia.org/wiki/ISO/IEC_9126
6. http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=22749
In any software product one has functional and non-functional requirements. It is always easier (is it so?) to identify and define functional requirements. But not so easy to define non functional. With increasing experience of software development communities, traditional non functional requirements like availability, usability, robustness (http://en.wikipedia.org/wiki/Non-functional_requirement) becoming commodity. But with changing business and technological landscape, new set of non functional requirements are emerging.
1. Open API ( synchronous and/or asynchronous)
a. Remote Object
b. Service (for example)
i. SOAP based Web Service
ii. REST Based Web Service
iii. JSON based web service
2. Multiple Channel Access (for example)
a. Connected Desktop (web browser)
b. Disconnected Desktop
c. Mobile application
d. RSS/Atom
e. WAP
f. Mobile browser
3. 3rd party/partners can build on your platform/product
4. Product as vehicle for 3rd party content
5. User as editor of relevant content
6. Content is made available to user when it is ready (push mechanism or at least reactive alert)
7. User add ancillary data ( like rating, reviews, ranking, link submission, recommendations, etc)
8. Settings/configurations can be exported and imported
9. Allow product to run as slave as well as master while integrating with other applications
10. User as owner of identity
a. Published Privacy policy with some control to end users
b. Authentication and authorization using industry wide acceptable standards ( like OpenID, facebook Id, google ID, Yahoo ID, etc)
11. Variable licensing options (for example)
a. Transaction based
b. Revenue sharing
c. User based
d. Fixed onetime cost
e. Time based
f. Cloud compliant
g. Processor based
h. Virtualization compliant
12. Social Networking features
13. Serving high band width as well as low band width environment
14. Information and data search capability
15. Domain Specific language
16. Framework for customization
17. Support distributive SDLC with multiple out sourcing partners
18. Hardware independence
19. Place for online advertisement ( like google ad)
20. Open to migrate to cloud or to non cloud deployment
21. User Analytics
22. Dash board
a. Users
b. Administrators
c. Maintenance and support staff
23. Hooks to monitoring tools
24. Early release and flexible design & architecture to modify
25. Concepts of Roles and Permissions (Identity Management)
26. Multiple Browser compatibility
Reference
1. http://en.wikipedia.org/wiki/Non-functional_requirement
2. http://en.wikipedia.org/wiki/List_of_system_quality_attributes
3. http://broadcast.oreilly.com/2010/02/nonfunctional-requirements-how.html
4. http://en.wikipedia.org/wiki/Requirements_analysis
5. http://en.wikipedia.org/wiki/ISO/IEC_9126
6. http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=22749
Sunday, October 17, 2010
Saturday, October 16, 2010
Book Review: The New World of Wireless How to Compete in the 4G Revolution by Scott Snyder
Book Review: The New World of Wireless How to Compete in the 4G Revolution by Scott Snyder: Publisher- Wharton School Publishing: ISBN- 13: 978-0-13-700379-2
The New World of Wireless depicts two possible scenarios on effect of 4G technology on society and business. Book then focuses on business strategy to be adopted by enterprise to take advantage of scenarios emerging.
Certainly book projects new thought for business but it does not try to pick any cue from historical events and scenarios which has emerged in other industries.
Though book does not discuss this but both scenarios have parallel scenarios in today's world. Take example of computer operating systems (Microsoft Windows - dominant in consumer arena, UNIX - AIX, HP UX, Solaris, BSD etc - dominant in server market and linux and with its numerous variant trying to dominant consumer and server market simultaneously). Nature Align scenario is too good to be true due to current geo political conditions, IP related issues and desire of corporations to dominant the market (for example in social networking Google has tried to enforce its standard for communication - which miserably failed). On the same lines, Killer Bee scenario on the other extreme. I visualize scenario in wireless communication will be very similar to computer operating system, where no one standard dominates but each has strong presence in their respective fields and trying to encroach in others strong areas.
Scenario one, Virtual network provider (VNP) consolidates network capability from various network providers. Consumers get the network access via VNP. For example in Indian context, Virgin Mobile is acting not only over Tata Telecom netork but also over Reliance, Bharti, Vodaphone and others. Consumer logs into Virgin network (!) which in turn gets access to all underlying networks. This type of model is must for Nature Align scenario. Book is missing on such details.
Nevertheless, book provides fresh insight on 4G technologies on society and businesses. Book also introduces two important and interested concepts, Digital Swarm and Wireless IQ (WIQ).
I certainly recommend this book from strategic thinking perspective.
Disclaimer: I did not get paid to review this book, and I do not stand to gain anything if you buy the book. I have no relationship with the publisher or the author.
One can get more information about book and related topics from:
1. Amazon: http://www.amazon.com/New-World-Wireless-Revolution-ebook/dp/B002HMJY6U
2. Publisher - Wharton School Publishing http://www.whartonsp.com/store/product.aspx?isbn=013700379X
3. Podcast of Author http://www.enterpriseleadership.org/blogs/podcasts/2009/11/13/dr-scott-snyder-author-talks-about-4g-wireless-disruptive-technology-and-what-cios-need-to-do-now
4. Safari: http://my.safaribooksonline.com/9780137026845
5. Interview with author: http://www.smartplanet.com/people/blog/pure-genius/how-4g-accelerates-the-wireless-revolution-and-how-to-compete/826/
6. Author’s Employer: http://www.thinkdsi.com/index.asp
7. Review: http://strategicframing.com/2009/07/31/digital-swarms-anyone-the-new-world-of-wireless
8. Funny 4G: http://www.squidoo.com/What_Makes_4G_The_Inevitable_Future
9. Interesting site on Mobile and Wireless: http://mobilebeyond.net/
The New World of Wireless depicts two possible scenarios on effect of 4G technology on society and business. Book then focuses on business strategy to be adopted by enterprise to take advantage of scenarios emerging.
Certainly book projects new thought for business but it does not try to pick any cue from historical events and scenarios which has emerged in other industries.
Though book does not discuss this but both scenarios have parallel scenarios in today's world. Take example of computer operating systems (Microsoft Windows - dominant in consumer arena, UNIX - AIX, HP UX, Solaris, BSD etc - dominant in server market and linux and with its numerous variant trying to dominant consumer and server market simultaneously). Nature Align scenario is too good to be true due to current geo political conditions, IP related issues and desire of corporations to dominant the market (for example in social networking Google has tried to enforce its standard for communication - which miserably failed). On the same lines, Killer Bee scenario on the other extreme. I visualize scenario in wireless communication will be very similar to computer operating system, where no one standard dominates but each has strong presence in their respective fields and trying to encroach in others strong areas.
Scenario one, Virtual network provider (VNP) consolidates network capability from various network providers. Consumers get the network access via VNP. For example in Indian context, Virgin Mobile is acting not only over Tata Telecom netork but also over Reliance, Bharti, Vodaphone and others. Consumer logs into Virgin network (!) which in turn gets access to all underlying networks. This type of model is must for Nature Align scenario. Book is missing on such details.
Nevertheless, book provides fresh insight on 4G technologies on society and businesses. Book also introduces two important and interested concepts, Digital Swarm and Wireless IQ (WIQ).
I certainly recommend this book from strategic thinking perspective.
Disclaimer: I did not get paid to review this book, and I do not stand to gain anything if you buy the book. I have no relationship with the publisher or the author.
One can get more information about book and related topics from:
1. Amazon: http://www.amazon.com/New-World-Wireless-Revolution-ebook/dp/B002HMJY6U
2. Publisher - Wharton School Publishing http://www.whartonsp.com/store/product.aspx?isbn=013700379X
3. Podcast of Author http://www.enterpriseleadership.org/blogs/podcasts/2009/11/13/dr-scott-snyder-author-talks-about-4g-wireless-disruptive-technology-and-what-cios-need-to-do-now
4. Safari: http://my.safaribooksonline.com/9780137026845
5. Interview with author: http://www.smartplanet.com/people/blog/pure-genius/how-4g-accelerates-the-wireless-revolution-and-how-to-compete/826/
6. Author’s Employer: http://www.thinkdsi.com/index.asp
7. Review: http://strategicframing.com/2009/07/31/digital-swarms-anyone-the-new-world-of-wireless
8. Funny 4G: http://www.squidoo.com/What_Makes_4G_The_Inevitable_Future
9. Interesting site on Mobile and Wireless: http://mobilebeyond.net/
Friday, October 15, 2010
Thursday, October 14, 2010
Wednesday, October 13, 2010
Tuesday, October 12, 2010
Monday, October 11, 2010
Software Architecture and Design – How to Change!
With time everything changes, so the architecture and design of any software. To avoid Architectural Erosion, one has to manage Architectural changes with great care. To do required changes following are the few techniques:
1. Adaptation: In this technique, single implementation is maintained but it offers interfaces to adopt demanded behavior. To accomplish this configuration parameters (design or compile/build or deployment or run time) are adjusted. Even reimplementation or patch to source code is used. Adapter and Inversion of Control pattern is most used example of this technique. Inheritance is also one of the popular way to achieve adaptation.
2. Replacement: In this technique, various implementations are available. As per the need specific implementation is used.
3. Extension: In this technique, component provides facility to add additional components as and when required (design or compile/build or deployment or run time). This is also called plug-in approach.
To understand Architectural Erosion one can use Inter Service Dependency Model.
Reference:
1. http://architecture-soa-bpm-eai.blogspot.com/2009/01/inter-service-dependency-model.html
2. http://www.methodsandtools.com/archive/archive.php?id=85
3. http://www.lattix.com/g_architecture
4. http://blog.softwarearchitecture.com/2009/04/10-principles-of-change-management.html
1. Adaptation: In this technique, single implementation is maintained but it offers interfaces to adopt demanded behavior. To accomplish this configuration parameters (design or compile/build or deployment or run time) are adjusted. Even reimplementation or patch to source code is used. Adapter and Inversion of Control pattern is most used example of this technique. Inheritance is also one of the popular way to achieve adaptation.
2. Replacement: In this technique, various implementations are available. As per the need specific implementation is used.
3. Extension: In this technique, component provides facility to add additional components as and when required (design or compile/build or deployment or run time). This is also called plug-in approach.
To understand Architectural Erosion one can use Inter Service Dependency Model.
Reference:
1. http://architecture-soa-bpm-eai.blogspot.com/2009/01/inter-service-dependency-model.html
2. http://www.methodsandtools.com/archive/archive.php?id=85
3. http://www.lattix.com/g_architecture
4. http://blog.softwarearchitecture.com/2009/04/10-principles-of-change-management.html
Subscribe to:
Posts (Atom)
Posts
