Home Forums WPF controls Xceed DataGrid for WPF Documentation Feedback: Snippets

Viewing 15 posts - 1 through 15 (of 20 total)
  • Author
    Posts
  • Xceed Support
    Member
    Post count: 5658
    #24171 |

    Hey Guys,

    I have a question in regards to the snippets found throughout the documentation that I would appreciate your feedback on; notably, the “How-to” section. Here goes:

    I recently created a “Snippet Explorer” which is a searchable XBAP application that contains all the snippets found throughout the documentation. All the snippets that match the search keywords are displayed and the search criteria highlighted. The code associated with the snippet can also be copied to the clipboard. Links to the relevant documentation are also included.

    My question: Should I remove the How-to section and only have the Snippet Explorer? Or would you prefer to keep the How-to section like it is? Keep in mind that the snippets in each actual page and that any links launched from the explorer will map to the online documentation.

    If you don’t like either option, how would you like to see the How-to’s?

    Thanks in advance for the feedback, I appreciate it!

    Imported from legacy forums. Posted by Jenny [Xceed] (had 11703 views)

    User (Old forums)
    Member
    Post count: 23064

    Hi Jenny,

    As for Documentation…I would personally like to see
    a) A Reference section (i.e. a Snippet explorer) in which the code is shown in
    i) XAML within the <Window></Window>
    ii) Syphoned off and shown how it may possible be used as a XAML resource.
    iii) C# equivalent for putting in the code-behind. (Better compilation checking and IntelliSense).

    b) Retain the How to section by giving References to the ‘Reference Section”. This would means that you can build doucmentation all the way up to a “Solution” level if need be without actually writing too much text. So, typically you might Say “To do this…Use this Template , that Style, this type of Binding at ‘Snippet Explorer’ x, y, and z “.

    c) Best Practices and Techniques worth avoiding (for instance you flagged a warning about continually doing a Cell.EndEdit Cell.BeginEdit just today).

    I realize it might be tedious to start up but the benefits would start coming through in not only reduced tine to expose a solution idea or concept at Xceed but in quickly answering annoying chaps like myself quickly and precisely 😉 …

    Anyway…just my twopenneth worth…

    Dezzz.

    Imported from legacy forums. Posted by Desmond (had 544 views)

    Xceed Support
    Member
    Post count: 5658

    Hi Dezzz,

    I would like to clarify what you mean by “(b)”. Are you saying that you prefer to have sections of code (e.g., a template or style for a particular element) without it being in context (i.e., not compilable)?

    For example, currently I have the following snippet:

    <code>
    <Grid xmlns:xcdg=”http://schemas.xceed.com/wpf/xaml/datagrid”&gt;
    <Grid.Resources>
    <Style TargetType=”{x:Type xcdg:DataCell}”>
    <Setter Property=”CurrentForeground”>
    <Setter.Value>
    <SolidColorBrush Color=”Yellow”/>
    </Setter.Value>
    </Setter>
    <Setter Property=”CurrentBackground”>
    <Setter.Value>
    <SolidColorBrush Color=”Orange”/>
    </Setter.Value>
    </Setter>
    </Style>
    <xcdg:DataGridCollectionViewSource x:Key=”cvs_orders”
    Source=”{Binding Source={x:Static Application.Current},
    Path=Orders}”/>
    </Grid.Resources>

    <xcdg:DataGridControl x:Name=”OrdersGrid”
    ItemsSource=”{Binding Source={StaticResource cvs_orders}}”/>
    </Grid>
    </code>

    From what I understand, you would prefer such a snippet to be reduced only to the style and separately the creation of the datagrid and then, in the documentation, say use snippet a and b? Would this be only in the how-to section or throughout the documentation? Would you like to have both in the snippet explorer?

    I am waiting on new features to arrive from the developers, so now is the time to do any modifications to the documentation 🙂

    Thanks again!

    Imported from legacy forums. Posted by Jenny [Xceed] (had 416 views)

    User (Old forums)
    Member
    Post count: 23064

    Hi Jenny,
    In a Corporate environment when we are talking about rollling out a System (application) with the number of screens potentially into the hundreds, then there is a real requirement to have as much XAML as possible in Resource Dictionaries. Whilst quite a bit of the XAML is easily ‘resourced’ off (i.e. from a syntax point of view), there are occasions when it is not immediately apparent or obvious how its done (or coded).

    Supposing the requirement was for some columns with Orange background and some with a Blue background? What would you have to change in your code above to allow the developer to use what they want when they want it. The changes required may not be that apparent!

    The aim of most developers is to have the minimum amount of code to change when a maintenance request comes through….or in developing a ‘similar’ screen but with just some fundamentals changed. Re-usable code is the dream of all developers as it ultimately leads to faster roll-out times when the ‘library functions’ or in this case Resource declarations are created.

    Best Regards,

    Dezzz.

    Imported from legacy forums. Posted by Desmond (had 566 views)

    User (Old forums)
    Member
    Post count: 23064

    Hi Jenny,

    It’s great that you’re improving the accessibility of the documentation and I’m sure the “Snippet Explorer” will get a lot of use.

    Please keep the “How-to’s” where they are and make the “Snippet Explorer” an additional resource. If anything, the docs could use more How-to examples, not less (for example solutions provided by Xceed staff that appear in forum threads which are not available in the docs).

    When you’re reading documentation, the best explanation is often just a short example and the “How-to’s” throughout the documentation serve that very important purpose.

    Almost every time I search the MSDN documentation, I’m thankful for those small inline examples.

    Full blow SDK examples can always be downloaded from MSDN, studied, debugged and run interactively, but the small quick examples play a VITAL roll in explaining the material presented.

    Additionally, the standalone “How-to” examples embedded in the documentation make it possible to study code without having to have an installed and working version of Net 3.0 on your system.

    I have a small outdated laptop that I use for study. The Xceed standalone help files are on it and I can study examples without .NET 3.0 being installed. Similarly when I review the documentation from the web on any computer, the example “How-tos” are present for study, regardless of that machine’s ability to run an XBAP app.

    The beauty of small “How-to” examples is that they get right to the point without all the clutter of a full application.

    Thanks,
    Richie

    Imported from legacy forums. Posted by Richard (had 426 views)

    User (Old forums)
    Member
    Post count: 23064

    I too think that the snippets are a vital part of the documentation and should be left where they are.

    To be honest, too often I’ve seen “search” options in documentation fall short of what I’m actually looking for. They return too many or too few results and in the case of snippets those results would be outside of their context (what exactly is being shown). While I might use the snippet search tool, I’m pretty sure my primary exposure to the snippets will remain through normal documentation browsing.

    On another note, I also agree with Dazzz the snippets being provided usually do include more than necessary to illustrate the point in some cases. For example the snippet you provided above. I would probably have done the following instead

    —-
    <Grid xmlns:xcdg=”http://schemas.xceed.com/wpf/xaml/datagrid”&gt;
    <Grid.Resources>

    <Style TargetType=”{x:Type xcdg:DataCell}”>
    <Setter Property=”CurrentForeground”>
    <Setter.Value>
    <SolidColorBrush Color=”Yellow”/>
    </Setter.Value>
    </Setter>

    <Setter Property=”CurrentBackground”>
    <Setter.Value>
    <SolidColorBrush Color=”Orange”/>
    </Setter.Value>
    </Setter>
    </Style>
    </Grid.Resources>

    <xcdg:DataGridControl x:Name=”OrdersGrid”/>
    </Grid>
    —-

    This is a minor change, but it presents a “Resource” section that includes only the style I’m actually trying to effect.

    Thanks for everything

    Imported from legacy forums. Posted by Duane (had 979 views)

    Xceed Support
    Member
    Post count: 5658

    I just finished making a modification to the snippets where I “grayed-out” the sections of the code that are not the main focus of the snippet, which is in black. That way, copying the code with the copy code button will copy the entire, compilable snippet all-the-while making sure that the “important” part is easily found when looking at the snippet in the documentation.

    Does that sound like a good compromise?

    I will be leaving the How-to section as so far you all would like me to leave it there 🙂

    Another question:

    I have the possibility to apply language color schemes to the snippets. Would this be preferred? I cannot “gray-out” sections in this case.

    Thanks for the feedback!

    Imported from legacy forums. Posted by Jenny [Xceed] (had 435 views)

    User (Old forums)
    Member
    Post count: 23064

    I’m using the online docs, but can’t see any difference yet (mabey i’m not suppose to)

    Anyways in reply to your question about language color schemes I’d say either or is good. language color schemes can be VERY nice for large chunks of code, but small snippets are generally managable with just proper spacing.

    For now I’d say stick with the greying out, but like I said, either or is good.

    Imported from legacy forums. Posted by Duane (had 707 views)

    Xceed Support
    Member
    Post count: 5658

    The new version is not public yet 🙂

    Anyone else have an opinion on the grayed-out vs. color-schemed?

    Imported from legacy forums. Posted by Jenny [Xceed] (had 490 views)

    User (Old forums)
    Member
    Post count: 23064

    IMHO Colour-Schemed…..

    Dezzz.

    Imported from legacy forums. Posted by Desmond (had 973 views)

    User (Old forums)
    Member
    Post count: 23064

    It’s hard for me to comment on the color vs grayed out question without seeing an example.

    But of course that won’t stop me … 🙂

    I think the color text really helps reading code. Instead of graying out less essential code, perhaps you could just use a nice comment to denote the relative “importance” of the sections.

    The problem is that what may be non-essential to one developer who knows a lot may be absolutely essential to another who knows less.

    With WPF it’s amazing how many little corners there can be, it is such a rich programming model.

    While I like the current snippet examples in documentation a lot, I’ve sometimes found myself wishing they had more detail. This was especially true at the very beginning of my exporations with Xceed DataGrid for WPF. Additionally, I spent a lot of time looking for code examples in the forum posts that I couldn’t find in the documentation.

    For every snippet it would be nice if there was a complete working example for just that section of the documentation. A fully functional ZIP you could download and fire up into Visual Studio for all the experimentation you desire.

    I’d vote for collapsable sections over grayed out sections. Something similar to a region, if you don’t want to see a section of code that has a comment indicating “…the nitty gritty details…” you could just collapse it, voila, you don’t have to worry about looking at that code anymore.

    However, for the newer user, each and every line of the example may be a gold mine of information.

    Thanks for the work you’re doing on the documentation.

    Thanks,
    Richie

    Imported from legacy forums. Posted by Richard (had 735 views)

    Xceed Support
    Member
    Post count: 5658

    <a href=”http://doc.xceedsoft.com/products/images/grayed_code.gif”>Grayed-out</a&gt;
    <a href=”http://doc.xceedsoft.com/products/images/colored_code.gif”>Colored</a&gt;

    Opinions still the same? (the font of the colored example is a bit off. it will/should look like the font in the grayed-out example)

    Imported from legacy forums. Posted by Jenny [Xceed] (had 607 views)

    User (Old forums)
    Member
    Post count: 23064

    I assume the Grayed-out example would actually include color for the part that isn’t grayed-out… right?

    That said, I see what why you like it, it’s a really cool way to ignore the stuff, but glance at it at the same time.

    I hate having to choose, I’d like to have both options 🙂 ….

    The grayed-out effect definitely works nicely, but I’d really love to see it in color if at some point in time when I decide to review it.

    The improves you’re making are great so I won’t complain too much either way… I’ll leave it to the collective vote.

    Thanks for the pictures.

    Rich

    Imported from legacy forums. Posted by Richard (had 618 views)

    Xceed Support
    Member
    Post count: 5658

    “I assume the Grayed-out example would actually include color for the part that isn’t grayed-out… right?”

    I am trying, but it is not working out 🙁 I’ll keep working on it.

    I tried putting everything in color but I found it hard to read and difficult to pinpoint the “important” parts (I have no control over how the color-coded code is displayed).

    Ideally, I would like to have some color in the grayed-out. If I can’t get it to work, I have decided to use the grayed-out rather than the color coded.

    Thank you for the encouraging words! I appreciate it 🙂

    Imported from legacy forums. Posted by Jenny [Xceed] (had 375 views)

    User (Old forums)
    Member
    Post count: 23064

    Hi Jenny,

    One thought…

    If you have the option to change the opacity of the text, maybe leaving everything in color and changing the opacity of the less important stuff would give you the same effect as grayed-out.

    Thanks,
    Rich

    Imported from legacy forums. Posted by Richard (had 710 views)

Viewing 15 posts - 1 through 15 (of 20 total)
  • You must be logged in to reply to this topic.