Crisis #1 – WTF Happened to the Git Reference

For those of us who have not had the “aha” Git moment, and do not have every Git command memorized, a complete reference is indispensable. For G_d knows how long more topics in the only known complete reference have been broken than I care to count. Looking up every Git issue we encounter on Stackoverflow without a reference to put it all in context is a helluva way to come up to speed. This is like the Git cognoscenti putting a big sign on their clubhouse, “Hey, we learned it on our own”.

UPDATE: Github fixed this October 30. Thanks Github!

Crisis #2 — Microsoft Research Abandons Power Pack Collections Documentation

And the same goes for the Collections.Tagged documentation page. For now you can still get collections and collections.tagged on the Way Back Machine.

OK, not that many people care about F#, but if you come to my blog there is a good chance you do. MSR has probably been intending to take this page down for a long time. It was documenting an old release of the Power Pack Collections, but still better than nothing.

HashSet – Who cares. I think this got deprecated to something in the .Net generics collection.

HashMultiMap – Seems no one cares about this one either. Even though it is not a functional data structure, someone might find it useful, if only it were documented.

LazyList – <hyperbole>Everybody</hyperbole> uses LazyList. In fact, I’m baffled why the FSharp Team hasn’t integrated LazyList into FSharp.Core. It is in the Microsoft.FSharp.Collections namespace. So it’s bad enough F# newbies wonder why they can’t call up the docs in Visual Studio Help Viewer.

The Unifying Crisis

What I consider a bigger deal is the difficulty in formatting open source project documentation. Let’s face it. People who like to code open source projects like to code, and generally dislike writing documentation. My interest here is primarily .NET open source projects (my wish list applies to .NET projects), and admittedly I have not dug very deep into the solution. Open source authors and consumers would benefit greatly, and make project adoption much easier, if there were good tools for generating nicely formatted documentation outlines.

Ideally a markup language to generate Visual Studio Help Viewer format. (And ideally a way to integrate it into VS Help Viewer.)

Ideally a tool to generate a reference skeleton from the project code.

Less ideal would be generation and markup for any decent pseudo-standardized reference format. (There is probably something already available that will do this into Java Docs format, but really, do we have to?)

And I am sure there are some who are thinking “Unix man pages are just fine”.