 |
 | Home | Contact Us | FAQ | Search & Site Map | Link to Us |
 | Sign In | Join | Other 45 Sites in Network |
.NET Forum / Visual Studio.NET / Extensibility / October 2006Where's the documentation
Hi there, Does anyone know whether MSFT has a comprehensive link describing the "Properties" member (collection) of the main extensibility classes such as "Project", "ProjectItem", etc. I've searched high and low and the documentation is extremely sparse or virtually non-existent (when describing each individual property in the collection). Moreover, some mainstream properties are available for certain projects only but not others (e.g., the "Extension" property on a "ProjectItem" which is available in C# and VB only). It's not like MSFT to publish such poor documentation which forces programmers to rely on guesswork and that can only lead to instability. Note that even if you enumerate a given properties collection to see what's there, it's still pure guesswork as to the nature of each property, the projects that actually support it, its dependability (whether it's always supported/available), etc. Can anyone shed any light on the situation. Thanks Hi Jack, By their own nature, those properties are kind of "late-bound", which means that they depend on the provider behind them, so they can't be documented in the general documentation for the VS extensibility. The only properties that are standarized are the ones belonging to the Project / ProjectItem class, an even some kind of projects can throw a "not implemented" exception, like the so called unmodeled projects (database projects and such). The bottom line is that you should not rely heavily on those properties, and, if really needed, you have to discover on your own the names, language packages and versions supported. For example, some properties in VS.NET 2003 have disappeared in VS 2005, specially for web projects, that follow a different model (web site vs web application). I know it's a pain, my own MZ-Tools add-in suffered it, but that's how things are.  SignatureBest regards, Carlos J. Quintero MZ-Tools: Productivity add-ins for Visual Studio You can code, design and document much faster: http://www.mztools.com > Hi there, > [quoted text clipped - 12 lines] > dependability (whether it's always supported/available), etc. Can anyone > shed any light on the situation. Thanks > By their own nature, those properties are kind of "late-bound", which > means that they depend on the provider behind them, so they can't be [quoted text clipped - 12 lines] > I know it's a pain, my own MZ-Tools add-in suffered it, but that's how > things are. Thanks for the feedback. Unfortunately, the Project/ProjectItem properties are the ones I'm primarly interested in but I can' find any proper documentation even for them (and I only need to rely on them where the info isn't available through other means). Moreover, while I recognize that these properties vary from project type to project type and even within a given project type (the very reason for making them "late-bound" in the first place), that's no reason for MSFT not to document them. MSFT is the provider for all standard (out-of-the-box) projects in VS so if a programmer doesn't know what a property is, how to use it, which projects support it, whether it's always supported (depending on various factors), etc., then the information is effectively useless. You can't safely guess at it nor should you have to (noting that self-discovery is impractical and unreliable). In any case, thanks again for your help (appreciated). Ok, there is a small attempt in VS 2005 to document some of them using the VSLangProj80.ProjectProperties, FileProperties, FolderProperties and the such: ProjectProperties3 Interface http://msdn2.microsoft.com/en-us/library/vslangproj80.projectproperties3.aspx See also: How to Access Properties of Specific Project Types http://blogs.msdn.com/jim_glass/archive/2005/05/25/421798.aspx SignatureBest regards, Carlos J. Quintero MZ-Tools: Productivity add-ins for Visual Studio You can code, design and document much faster: http://www.mztools.com >> By their own nature, those properties are kind of "late-bound", which >> means that they depend on the provider behind them, so they can't be [quoted text clipped - 26 lines] > at it nor should you have to (noting that self-discovery is impractical > and unreliable). In any case, thanks again for your help (appreciated). > Ok, there is a small attempt in VS 2005 to document some of them using the > VSLangProj80.ProjectProperties, FileProperties, FolderProperties and the > such: > > ProjectProperties3 Interface > http://msdn2.microsoft.com/en-us/library/vslangproj80.projectproperties3.aspx Yes, but this has been my contention all along. You'll find that none of these properties are actually documented and in fact, all of them just repeat the same ineffective information (something I'm sure you must be aware of by now). I think someone dropped the ball at MSFT. > It's not like MSFT to publish such poor documentation which forces > programmers to rely on guesswork and that can only lead to instability. Oh really, Since when? ;-) SignatureSteve Maillet EmbeddedFusion www.EmbeddedFusion.com smaillet at EmbeddedFusion dot com >> It's not like MSFT to publish such poor documentation which forces >> programmers to rely on guesswork and that can only lead to instability. > Oh really, Since when? ;-) The .NET documentation isn't fully mature IMO but generally speaking, the professionalism of MSFT's documentation is self-evident (MSDN clearly being a high-quality and comprehensive piece of work) >The .NET documentation isn't fully mature IMO That would be a mild way of phrasing it. > but generally speaking, the professionalism of MSFT's documentation is > self-evident (MSDN clearly being a high-quality and comprehensive piece of > work) I'd have to completely disagree with that. It's one of the most infuriatingly bad pile of stuff called documentation. Most of it is machine generated with a one line statement, which happened to be written be a person that is otherwise intuitively obvious to the casual observer and therefore provides no real useful information. If you already know the API you want and just can't remember the parameters it's fine. For someone trying to learn something new - forget it. Searches are also pretty useless too, virtually always end up with 500+ results 99.99999% of which are completely irrelevant and the methods of narrowing down the search are awful. You can get to the correct info faster by going to the web and using Google - usually you find a third party article that covers the subject better in the end. SignatureSteve Maillet EmbeddedFusion www.EmbeddedFusion.com smaillet at EmbeddedFusion dot com > >The .NET documentation isn't fully mature IMO > That would be a mild way of phrasing it. [quoted text clipped - 14 lines] > using Google - usually you find a third party article that covers the > subject better in the end. I agree with you on some points we could get into here. As a simple example, removal of the ability to search your search results was a very bad idea. They've moved backwards instead of forward here (VS6 was better). I also find that the .NET docs in particular are much too light on the info which explains my earlier comment. You have to put things in perspective however. Windows is a huge OS and for the most part MSFT has done a great job of documenting it. The online help is extensive and polished in spite of the naysayers. That's no small feat given the inherent complexity and while it's easy to complain (yes, I've done my own share of griping over the years), I'd like to see someone do a better job. >The online help is extensive and polished in spite of the naysayers. Just because it looks good doesn't make it good documentation. Good documentation needs to provide users with the information they need use the products efficiently. Good documentation should do so in a manner that gets you going from square 1 (or square 0 if you're not a VB programmer! ;-) ) It needs to explain the "why" just as much as the "How". The big picture context of a set of related things needs to be there. (and it is this aspect that is seriously lacking from pretty much all MS documentation.) MS docs have always been focused almost exclusively as Reference Material only. While that was OK in the days of DOS and Windows 1.0. By the time we got to Windows 3.x and NT + Win32 that was no longer valid. The systems have gotten dramatically more complex since then and MS NEEDs to apply serious effort on the contextual side of things as well. >I'd like to see someone do a better job. See any of the works of, Jeff Prosise, Doug Boling, Charles Petzold or Jeffery Richter. They, and others, do a vastly superior job of documenting windows then MS does. SignatureSteve Maillet EmbeddedFusion www.EmbeddedFusion.com smaillet at EmbeddedFusion dot com >>I'd like to see someone do a better job. > See any of the works of, Jeff Prosise, Doug Boling, Charles Petzold or > Jeffery Richter. They, and others, do a vastly superior job of documenting > windows then MS does. Your analogy is completely inaccurate. MSFT isn't a person, it's a large organization consisting of many people.You're equating (comparatively) tiny works written by a select group of highly experienced individuals to a monolithic documentation system written by thousands. You can put all the above authors in charge at MSFT and they wouldn't improve the situation. MSFT has all the resources one could ever dream of at its disposal and many of the world's smartest people working for them. And yet they still can't do right by many. If they can't, then who do you think could? >Your analogy is completely inaccurate. MSFT isn't a person, it's a large >organization consisting of many people.You're equating (comparatively) tiny >works written by a select group of highly experienced individuals to a >monolithic documentation system written by thousands. The docs are NOT written by thousands of people. The docs teams at MS for various products are surprisingly small in comparison to what you would think. The authors mentioned all create more and better documentation in less time then the MS docs teams do. However, the number of people is mostly irrelevant. It's the flow of information and the focus of the content, e.g. the architecture and design of documentation that is the problem not the number of bodies cranking out more reference material. > You can put all the above authors in charge at MSFT and they wouldn't > improve the situation. That's a debatable point I clearly disagree with. The expertise of those authors, if utilized to train and refocus the efforts of the existing tech writing staff, would have a HUGE impact on the quality of the documentation. Again the problem isn't the body count of the worker bees, it's the fundamental lack of a comprehensive and consistent design philosophy focused on something other than strictly reference material. The authors I mentioned all understand the need for placing information in proper context so that the minutiae of detail can be comprehended as and integral part of a greater whole. Their expertise and leadership in that aspect alone would dramatically turn around the quality level of the docs. >MSFT has all the resources one could ever dream of at its disposal and many >of the world's smartest people working for them. That's not necessarily an accurate statement of reality. They have good smart people and some lazy and dumb ones too. Just like every other company. They also have chosen very tight budgets for specific activities and have a stated philosophy of running lean and mean by keeping staffing to the lowest possible levels. They are not the almighty magical best that anyone can do that your statement implies. The sheer volume of complaints about the documentation is a testament to that fact. > And yet they still can't do right by many. If they can't, then who do you > think could? Just because MS hasn't *chosen* to do it right doesn't mean they can't *choose* to do so. It's a matter of choosing to create documentation that is something beyond basic reference material and thus more useful to users. SignatureSteve Maillet EmbeddedFusion www.EmbeddedFusion.com smaillet at EmbeddedFusion dot com > The docs are NOT written by thousands of people. The docs teams at MS for > various products are surprisingly small in comparison to what you would [quoted text clipped - 3 lines] > the architecture and design of documentation that is the problem not the > number of bodies cranking out more reference material. The sheer volume of documentation in MSDN (APIs and articles) was clearly amassed and written by thousands over the years. You're completely ignoring the huge number of architects and programmers whose specialized knowledge had to be collected, organized and documented. Who do you think did that? A few technical writers? > That's a debatable point I clearly disagree with. The expertise of those > authors, if utilized to train and refocus the efforts of the existing tech > writing staff, would have a HUGE impact on the quality of the documentation. ... > ... Their expertise and leadership in that aspect alone would > dramatically turn around the quality level of the docs. Absolutely not. The quality of work produced by any human endeavour decreases with the size of the task and number of people involved. It's just the reality of things. Moreover, an expert can't easily impart his years of wisdom and expertise to a large number of people. Each individual has to acquire that skill on his own even with the help and guidance of the experienced. Petzold isn't going to magically turn MSFT's staff into himself, nor is he going to personally review the work of a large body of people. In any case, you continue to imply that MSFT doesn't already have some of the best in the field. They do. So how is it then that the best-equipped organization in the world for performing this task on the scales involved, which already has many of the highly skilled people you're looking for, still can't get it right in your book (seriously, do you really think another company would have done better, or that by simply putting Petzold in charge, the documentation would have then met your expectations) > That's not necessarily an accurate statement of reality. They have good > smart people and some lazy and dumb ones too. Just like every other company. [quoted text clipped - 3 lines] > that your statement implies. The sheer volume of complaints about the > documentation is a testament to that fact. Lowest possible levels? Most developers can't crank out more than a few lines of code without botching things up. Yet MSFT created a huge and very complicated OS which is reasonably stable given the inherent complexities involved (and all the backwards compatibility issues). You think second-rate developers could have managed that? As for as the documentation, nobody's implying it's the best that man can produce. MSFT isn't a think tank however with 20 years on it hands. It's a profit-based company that needs to get its product to market in a reasonable amount of time. For the time that it had, the documentation it produced is extremely good and it's almost a certainty that no else could have done better under the same circumstances. > > And yet they still can't do right by many. If they can't, then who do you > > think could? > Just because MS hasn't *chosen* to do it right doesn't mean they can't > *choose* to do so. It's a matter of choosing to create documentation that is > something beyond basic reference material and thus more useful to users. There is certainly documentation beyond basic reference material. There are plenty of examples, written articles, and sample code. There are also gaps of course, cases of disorganization, and areas that certainly can be improved upon. I've had my own problems over a very long career (all on MSFT platforms) but for the most part I've been able to get my work done based primarily on the existing documentation. To state that MSFT has explicitly chosen not to do it right, or has purposely dumbed it down some way when clearly the documentation is professional by any reasonable standard (in spite of its shortcomings), is disingenuous IMO. >you continue to imply that MSFT doesn't already have some of the >best in the field. I'm not implying nor explicitly stating that. I'm just not assuming that they have 100% of the best and therefore no-one can do better, including them, which is what you and others here are implying (intentionally or not - only you can say, but that is the implication of what has been said thus far). As I said, they have good and bad people like anyone else. By assuming they have the best and no-one could do better you imply nothing CAN be done better, which is just bad for everyone. >seriously, do you really think another company would have done better, or >that by simply putting Petzold in charge, >the documentation would have then met your expectations) Yes as a matter of fact I do think that any of those authors in charge would have made a HUGE impact on the nature of the documentation. It's a matter of fundamental focuses. MS primary focus on the docs is reference. A HUGE amount of that these days is generated by a machine so the "sheer volume of content" most people talk about is at best misleading. The overwhelming bulk of .NET docs is all machine generated with only a small portion written by a developer and edited by a tech writer. That's then packed up and delivered as-is. Many times that's OK as reference a LOT of times it ends up with 99% machine generated stuff any moron can see from the function declaration but adds nothing else about it. >I've had my own problems over a very long career (all on MSFT >platforms) but for the most part I've been able to get my work done based >primarily on the existing documentation. Good, for you. And so have I, however, the amount of work and the time it took can be seriously reduced by better documentation, and in particular documentation that provides clear big picture context which cross links between the details of an individual parameter of a single function back up to the big picture contexts. That is what is fundamentally missing in the vast majority of the documentation and the real issue of this thread. >To state that MSFT has explicitly >chosen not to do it right, or has purposely dumbed it down some way when >clearly the documentation is professional by any reasonable standard (in >spite of its shortcomings), is disingenuous IMO. I have not said that so kindly please do not put words in my mouth. I did not say they "dumbed it down" in any way. I said they CHOOSE to focus on reference material in the design and implementation of their documentation and that that focus is not adequate anymore. To be clear - I am not declaring anything sinister or malevolent on Microsoft's part. Just a failure to grasp that the way they used to do things isn't appropriate anymore and, in fact, never was. It's just that in the earlier days, when habits and patterns for documentation were formed, nobody really cared as the complexity of things was so much less that the issues I'm talking about were not particularly significant. I would say that to imply that the docs, as they exist today, are as good as anyone can get, which is what you and others are saying here, is doing a disservice to both users and Microsoft. Microsoft needs feedback even if it's not flattering. The most common feedback they get is "the docs suck". I am giving vastly more specific feedback here about VERY particular and fundamental things that I see cause that sort of reaction. There is nothing "disingenuous" on my part here, so please leave the insults out of this. >Lowest possible levels? Most developers can't crank out more than a few >lines of code without botching things up. Yet MSFT created a huge and very >complicated OS which is reasonably stable given the inherent complexities >involved (and all the backwards compatibility issues). You think >second-rate >developers could have managed that? I said nothing about second rate developers. So again please don't put words in my mouth. I said that they "have a stated philosophy of running lean and mean by keeping staffing to the lowest possible levels." That is not a statement about quality of the staff but the *quantity*. One of Microsoft's business practices is deliberately understaffing by a small margin to push people hard. This makes sure that people are not getting lazy, which we all do from time to time, and it keeps head count expense down to the absolute down, which is always a HUGE expense. I happen to think this is a good practice that has worked VERY well for them. However, again, the actual body count is mostly irrelevant. It's the fundamental design and patterns those people follow that is at question here. When MS gets enough feedback that indicates people care enough, they WILL change, that's business and clearly they aren't stupid about business matters. But that won't happen if everyone just assumes that MS already has all the best people in the world and therefore things can't get any better then what we've got now. We need to provide specific feedback, and in this case I'm doing that in regards to a generalized observable pattern that permeates the whole documentation set known as MSDN. SignatureSteve Maillet EmbeddedFusion www.EmbeddedFusion.com smaillet at EmbeddedFusion dot com I think we can agree that we disagree. Statements like "it's one of the most infuriatingly bad pile of stuff" can't be taken as serious commentary. It clearly isn't even if you believe there's not enough descriptive information. Claiming that Petzold would have done a much better job is also idealistic (wishful thinking in fact). >I think we can agree that we disagree. That much is clear and we can agree on. > Statements like "it's one of the most infuriatingly bad pile of stuff" > can't be taken as serious commentary. It can very well be taken seriously as it's a an honest expression of the frustration and loss of time caused by the documentation. The docs ARE frustrating to work with and people regularly complain about them, I'm not the only one (Just the only one in this particular forum apparently). It's often difficult to find information that they know is supposed to be in there somewhere. To ignore that as a sign of something wrong is a best naive and at worst arrogant. >Claiming that Petzold would have done a much better job is also idealistic >(wishful thinking in fact). I think that people like the author's mentioned, not just Petzold, leading the docs team at MS would have made a HUGE difference in the docs. These kinds of writers fundamentally understand how to establish contextual information. Again it's all about what MS chooses to focus on in terms of the overall design of the documentation. The authors mentioned would have chosen a very different approach to the documentation design and it is precisely that kind of thinking MS needs to put in charge of the docs design now to improve them. SignatureSteve Maillet EmbeddedFusion www.EmbeddedFusion.com smaillet at EmbeddedFusion dot com Free MagazinesGet these publications absolutely FREE for up to 12 months. There are no hidden fees and no obligation. Simply choose a title, complete the application form and submit it. Read more ...
|
Reply to this Message
|
 Sign In
 Join
 My Latest Posts My Monitored Threads My Blog My Photo Gallery My Profile My Homepage Start New Thread Enable EMail Alerts Rate this Thread
|
©2008 Advenet LLC Privacy Policy - Terms of Use
This website includes both content owned or controlled by Advenet as well as content owned or controlled by third parties.