There are tasks you never know when you are done with. Documenting a complex API is one of those. I spent the last 6 weeks working on PostSharp 2.0 documentation, and it seems like I could spend another month on it. Yet, I think the result is already better than good enough – it’s actually pretty good. It’s available online here:

Note that the documentation refers to the last hot fix (1266+). Some features or APIs may not be available in the last CTP.

Inside the Book

The documentation is structured in two principal parts: deploying PostSharp, and developing with aspects.

The first part starts where the setup program stops: development environment may be very complex; deploying development tools to a large team may be very challenging. This chapter is based on my experience of supporting customers during last months. Special thanks go to Roy Osherove of TypeMock, who patiently went through all imaginable problems. His feedback prompted me to make deployment easier and to seriously document it. Thanks to all folks who reported issues or simply questions on the forum.

The second part is about aspect-oriented development itself. If you thought you knew everything about PostSharp, read this chapter. This is where you can contemplate the robustness and consistency of PostSharp 2.0 design. It’s elegant. Intelligent. Well-crafted. I’m proud of it.

Credits

Apart from Roy mentioned above, I would like to express my gratitude to two projects and the guys behind:

Eric Woodruff’s Sandcastle Help File Builder (SHFB) is wonderful. I deleted my 4-years old Sandcastle custom build scripts and switched to SHFB in a couple of hours. Writing content in MAML rocks. Thank you Eric for this excellent work!

Help Server of X-tensive.com is a superb product. You can judge by yourself on http://doc.sharpcrafters.com/. It’s a commercial product, but it’s definitively worth the money. Thank you Alex and team!

What’s next?

The documentation was the last big task to complete before the release. The rate of bug reports has dramatically decreased since the last CTP. So you can expect the RC very soon, hopefully next week.

Note: If you are still using PostSharp 1.5 and are not registered yet on our web site, do it now. Once PostSharp 2.0 will be RTWed, PostSharp 1.5 won’t be available any more for new users.

(I don’t give you absolute number of the color scale – I don’t know it myself -- so you can think the number-of-users-per-square-inch is a relevant unit.)

How I built this map

The map is constructed from web server logs, but I find it much more useful than anything I could see before. Google Analytics construct map overlays by drawing circles of different radius; since these circles largely overlap, it’s very difficult to get an idea of the real distribution of users.

This map has a strong mathematical foundation: it shows the Gaussian distribution of users in the world.

I used the following steps:

Start with IP of users, visitors, …

Map the IP to a geo location using GeoIP Free.

Associate each IP with a Gaussian distribution. Choose a small radius for precision, larger to see trends (here it’s pretty large). Note that computing the distance of a point from another, given their longitude and latitude, is not trivial.

For each point on the map, sum all distributions, then normalize. This results in a function [-180,180]x[-90x90] –> [0, 1].

Interesting findings

The proportion of PostSharp users is of course highly correlated to the demographics and the economics of the area itself. So the density of users in Europe is higher than in the USA, but there’re still more users in the USA than in Europe.

The map shows peeks in London and Taipei; Netherlands have a lot of PostSharp fans too. Germany has large areas of average densities, which suggests that German software development is less concentrated in cities than in other countries. A good thing. New-York is the home of may PostSharpers too. I would have loved to see a peek in Seatle, but…