New Documentation Structure

Topics: CAB & Smart Client Software Factory
May 17, 2006 at 3:36 PM
originally posted by: DarrelMiller

I've only taken a quick scan through the documentation, but I'm really impressed. That has to be the best structure I've ever seen for a developer help file.

I love the fact that everything is there, including what is it, how do I use it, what new concepts does it introduce, how do I extend it, and the explanation of the reference implementations.

- Grouping the automation and the manual steps makes a whole lot of sense.

- Personally I much prefer the CHM file.

- If the videos take a significant amount of time, I'd trade them for more detailed documentation. The easy stuff is easy in CAB, it's the hard stuff that is hard :-)
May 17, 2006 at 10:41 PM
originally posted by: fballem

Like Darrel, I've only taken a quick scan through the documentation. I agree with all of his points - including the excellent point that he makes about the videos. In a given amount of time, I would trade more detailed documentation for the videos. You may want to develop videos for post production - it would be useful as part of the training and support package after CAB is released, but the help documentation is what most of us would be using, and given time and resource constraints, that should be the primary focus.

Areas that I'm still not clear on - and may be difficult for others who are new to the project, is how to load modules in response to specific events, including the loading of the application itself, and how to use services that are not web services. More detail about these should be in the main part of the documentation, not buried in the reference applications.

As well, assuming a more traditional structure: Presentation, UI, Business Logic, Data Access, Data Storage and Management, it is clear that SC BAT addresses Presentation and UI. Detail around how to link it into the Business Logic layer, including specific implementations within the Guidance Package, would be most useful. You touch on it, indicating that Business Logic is included in the Module, but I'm still foggy about that (could be me). The same Business Entity and Logic could be used by many CAB Modules, and should be separated. Another reason for separating out the Business Entity and Logic is so that they can be wired to the Data Access access layer (which is out of scope for CAB).

more ...

Regards,

Flavelle
May 17, 2006 at 10:42 PM
originally posted by: fballem

... continued

Other specifics that should be addressed include how to add and remove items from the menu, toolbar, and status strip. Presumably each module will have items that they will want to add or remove from each, or to enable/disable in each. If there are multiple ways to implement this functionality, then discuss them, including the trade offs. For example, if XML files are used to load and remove items, then this could make it more difficult to internationalise the application (which is more efficiently done through Resource files).

If you have developed some patterns around Error Handling, particularly those using the Enterprise Library, then these should be described in the documentation. If there are recipes that are applicable, then these should be included in the Guidance Package. If there are other elements from Enterprise Library that are included in CAB, then these should also be described. When you document these links, focus on how they have been, or can be, IMPLEMENTED in CAB - a detailed explanation of the feature in Enterprise Library should be found in the Enterprise Library documentation.

The 'nice to haves' would be more detail around the implementation of an MVC pattern and a detailed discussion of when you would use MVC versus MVP. Should the same pattern be consistently applied across a project or can you mix and match? If you can mix and match, what are the circumstances under which you would do each.

A second 'nice to have' would be some detail around how to customise the introductory page that shows up with the Guidance Package. If we modify the Guidance Package - or if it is implemented in a large development shop, then this page will probably be customised, including the links to specific things. This may be more appropriate for the Guidance Automation team - and if it is, then please feel free to share the thought with them.

Regards,

Flavelle
May 18, 2006 at 3:42 AM
originally posted by: gxdata

Just had a quick glance through the CHM (which I prefer as help format), and running the 3 videos - which I would suggest ARE a good idea, even in their rough form. I like the way they're interspersed in the CHM - it works for me.

The Automation followed by Manual Steps is excellent.

One point: it's best to copy all the stuff into a folder with a short name, no spaces -else the link from CHM to Media Player fails to find the WMV file.

Ian Thomas
May 18, 2006 at 6:41 AM
originally posted by: fballem

Ian:

A couple of thoughts:

The concern that I have with doing the videos at this time is the effort - and will that effort take away from the depth and quality of the written documentation. If I recall correctly, SC-BAT is close to release date. If there will be no impact on the depth and quality of the written documentation, then I absolutely agree that the videos are useful - even in rough form. It's a question of priority and resource availability.

As for the format of the document (.chm, help 2, or .pdf), if it can be easily created from the same sources, then it should. If it cannot, then the existing .chm is perfectly satisfactory. It is what has been produced so far and has been used by all of us.

Regards,

Flavelle
May 18, 2006 at 7:12 AM
originally posted by: gxdata

Flavelle

I take the point on effort vs useful results wrto documentation.

But my reason for supporting the "rough form" webcasts and its integration with the interim documentation in the weekly/occasional CHM releases is that I'm sure that the actual uptake, or % of signed-in members of GDN p&p who download the "stuff" vs % of members who load the code and try it for themselves, is probably quite low.

I may be wrong, but I would guess that one of the aims of this whole community involvement in p&p is to get some of the "guidance" (love that new jargon word - it's like "refactoring") refined so that it is attractive enough - perhaps even seductive - for some of the enterprise folks (and others) give it a whirl. "It" being any one of a number of the frameworks / factories.

I'm sure there are thousands who are looking on, reading some of the docos, but not really taking it in; thinking "Is this really for us? How hard is it going to be?"

In my view, interspersing even some rough-edged webcasts into the conventional-format documentation is good.

I'm sure well-produced videos will be released later on.

As a side-comment:
Some of the Channel9 sessions are almost incomprehensible, though - I just looked at 30% of one starring the DDCPX Team "where they demo'ed MSBee, Managed Stack Explorer, and the TFS Administration Tool" - see http://blogs.msdn.com/ddcpxblg/archive/2006/03/23/559148.aspx - the filming was diabolical, despite a huge LCD screen set up facing away from the guys doing the demos. And the sound was pretty bad.

Well, my comments aren't adding much value to this topic, but that was my reason for liking the rough-cut videos.

ILT
May 18, 2006 at 7:25 AM
originally posted by: fballem

Ian:

So my question to you is:

If you were making the decision on whether to adopt/adapt this approach in your organisation, and you had limited exposure to this product and the project that produced it, would you feel that you had enough information to confidently make the decision to adopt/adapt it? And if you did adopt/adapt, do you feel that you have enough information to be able to adopt/adapt successfully?

As someone who has come late into this process and project, I believe that there are still significant challenges to being able to answer those questions. I'm not sure exactly what needs to be done, but I do know that the written documentation will be the major deciding factor - is it good enough to enable me to answer both questions. I am really intrigued with the possibilities for my firm and for my clients, but I'm not even close to comfortable enough to know how it will work. That's a learning curve issue, but it's a significant issue. The learning curve of how to effectively use this product still needs to be reduced.

I like the 'refactoring' (jargon :-) that Microsoft is doing to the documentation. I am really concerned about the quality, depth of coverage, and the ability to add sufficient information to make this product useful. I think (and these are my thoughts alone) that the videos have their place, but if it is a choice between the videos and improved written documentation, then I will always go for the written documentation. If Microsoft thinks they have the resources to do both, then both will add value. I have yet to run into a project where there are infinite resources with the right skills to deliver on everything in a given timeframe.

That's my two cents (Canadian) worth on the subject. At this point, the folks from Microsoft must be pulling their hair out trying to figure out "do we go with the videos or not?". Either decision has significant merits.

Thanks,
Flavelle
May 18, 2006 at 8:14 AM
originally posted by: askew

The decision to adopt new technology requires faith in the authors, imho, not documentation. I state this in responce to the argument that evaluators will be best served with more lines of documentation in order to adopt CAB, et al. I don't weigh it that heavily.

I like the videos, personally, and I think they are worth the effort and time. Some people respond better to mixed media than pure text, fwiw. I think it's more fun.
May 20, 2006 at 10:47 AM
originally posted by: rschrieken

The video's are ok and indeed fun to watch but the production time of a video will over run the time to write a chapter in the .chm file.

A trade off might be to have a general video on how to run a recipe and narate it in such a way that it matches the topics in any chapter describing a recipe.

A video will only be watched once, twice. A QuickSteps/Steps in Summary will be much more effictive in the long run.
May 20, 2006 at 11:04 AM
originally posted by: fballem

Just a question - when is SC BAT scheduled to be released? The reason I ask is one of time. Clearly there is an appetite for the videos, but a concern about the trade off in terms of the written (more frequently referred to) documentation.

Regards,

Flavelle
May 23, 2006 at 8:16 AM
originally posted by: dmateer

I agree with the sentiments of fballem's post of 05/17/2006 about things that need added to the "main" part of the documentation. The new documentation is improved, but (at least for this developer) there is still a large mental block in how to actually use the CAB and Smart Client Software Factory that keeps me teetering on the edge of abandoning it and returning to a less abstract way of developing Smart clients. I'm fully willing to admit my own obtuseness, but I'm having a lot more difficulty getting me head around this than other application blocks, patterns and practices, etc. Some lingering questions that might benefit from more step-by-step documentation / best practice references:

- I'm still not sure on the best way to physically organize workitems, modules, services, etc; each reference application (between CAB and SC factory) seems to have a different structure. This might seem trivial, but can impact ease of assembly deployment, one of the main advantages of the CAB/SC factory.

- I'm also still unclear on the difference and interaction between modules, workitems, smart parts, and components. In what order are the various methods of each executed / injected? How do I load modules on-the-fly?

- What is the "best practice" for loading services? In what object, and what method?

I'm sure these things are documented, either in this help file or the CAB, but I'm finding it difficut to comprehend.
May 24, 2006 at 11:41 AM
originally posted by: jUrbanowicz

Great improvement!!!

Thank you for adding the "New in this release section" a laudable best practice.

I know that for our team the Show Me's will be much better than an initial text explanation and a feature that we would like to add to our gat projects. We now go around showing each new person how to run our recipes when we could just have them run a "Show me".
I think that guidance on how and more importantly why to structure an application using CAB would be a great aide. Maybe in the "New in this release section" you could explain why you made changes. e.g. With the Smart Client Software Factory, the roles of CAB WorkItems have been split into two: containment and business logic. We recommend this refactoring to separate concerns and provide blah blah blah, allow for blah blah and ease of blah. Based on the containment and business logic pattern see http:// for more information….

but not just the following without a good explanation

State (bad idea, from Brad. Already is a container with d.i. properties, why do you need another bag of stuff?
Code (idea, from Brad. Should be separated out)

Thanks again for all the great work,
Jay