New user experience

Apr 26, 2011 at 8:44 AM


So obviously I'm new to Balder.  I figured you guys would value feedback about the new user experience since it's so important to attracting additional OSS contributors, so here are my thoughts with trying to get started.

First, some background.  I'm an experienced developer with quite a few years experience with C#, mainly in automation and tools dev.  However, I'm new to Silverlight and XNA, and not particularly experienced (quite rusty) with writing 3D code.  I'm going to be evaluating Balder for use in a small level-editor type app I want to develop quickly, in hoping not to have to do much of the low level 3D engine stuff myself.  (So far, looks promising.)  I decided to pull the code in case there are contributions I'd like to make as I go about it, and prefer working with project references over DLL references in general anyway.


* Codeplex Home tab: The "Project Description" spends too much time in the "sell this to me" space on mythology and not enough time describing what the project is.  This sentance could also use some rewording to avoid sounding like the purpose of Balder itself is just to provide documentation:  "The goal for Balder is to provide an extensive Documentation..."

* Also on the Home tab: the Rubik's cube and 2 of the Samplebrowser links are dead, in and just under the table of contents, respectively.

* It's not obvious where the "documentation" is.  The codeplex Documentation tab is where I expected to find at least some useful documentation, but instead it mentions a .chm file but doesn't even mention where to find it.  Is it only included w/the download package and not in the source control?

* The second place one might expect some helpful documentation would be that "readme" sitting in the root directory.  Hmm, not even a .txt extension to make it easy to open in modern operating systems?  Anyway, seems to be blank unless Hg screwed it up somehow.

* Third place to look: Balder->Documents... contains almost nothing.  Certainly nothing useful for this stage. 

* The fourth documentation I find is the "installation" pdf in balder\tutorials.  Wow.  Information that inaccurate is... less than useless; it is actively harmful.  Plus, PDF seems totally overkill for the document type and to my knowledge PDF does not generally merge/track well in source control.

* It would be nice to make it much more obvious what the prerequisites are.  It would be nice to be able to get started finding/downloading the correct versions of prerequisites while the source slowly downloads/retries/rollsback/retries/etc.  I finally figured out that yes I can try the Silverlight 5 beta (I didn't have any Silverlight installed) and then figured out the hard way that I needed the Visual Studio 2010 Service Pack 1 (which really appears to be more of a "massive software bundle with no options to pick and choose what you want" than a "service pack" but I digress).  Ideally, maintaining direct links is best.

* Ok time to build some soure.  Uh... can't believe i had to "search" for *.sln.  Solutions have their own folder instead of being placed in balder\source itself?  Strange choice but I guess I can see why since there are actually so many of them.

* I opened Balder_Silverlight.sln and a couple others - in many cases I had to delete and re-add references like "System.Xml.Linq".

* In many cases I also had to change the targeted silverlight version to 5 since the solution seemed to contain a mix of projects targeting 5 and projects targeting 4.

* Balder.Build sln failed to open two projects that indeed don't seem to exist (at least at their specified paths).

* Balder_Silverlight failed to build at the pre-build event for CompileShaders.cmd.  Couldn't find fxc to compile shaders...  looks like I stumbled on another setup step;  either I don't have it or don't have it in my path - I'll check that out another day but for now I just want to get this thing building, shaders or not, so I disabled execution of CompileShaders for now.  (Is compiling shaders really a necessary prerequisite for creating the balder DLL?)  I've also assumed I don't need to have XNA installed ATM in order to build the Silverlight version.

* It's strange to see things like tabs used instead of spaces in a source-controlled project, defying Visual Studio defaults; if one formats document (or deletes and retypes just the closing curly brace in a file) then almost every single line of code in the entire file will be "changed" and potentially be generating much checkin noise.  IMO it's much easier all around not to fight auto-formatting.  Perhaps even consider making the code largely StyleCop compliant?

* 20 warnings when compiling Balder_Silverlight... not an attractive thing for potential new contributors:

Warning 1 'Balder.Math.Vector' defines operator == or operator != but does not override Object.GetHashCode() C:\Balder\Source\Balder\Math\Vector.cs 26 16 Balder.Silverlight
Warning 2 'Balder.Math.Vector' overrides Object.Equals(object o) but does not override Object.GetHashCode() C:\Balder\Source\Balder\Math\Vector.cs 26 16 Balder.Silverlight
Warning 3 'Balder.Math.Dimension' overrides Object.Equals(object o) but does not override Object.GetHashCode() C:\Balder\Source\Balder\Math\Dimension.cs 30 15 Balder.Silverlight
Warning 4 'Balder.Math.Coordinate' overrides Object.Equals(object o) but does not override Object.GetHashCode() C:\Balder\Source\Balder\Math\Coordinate.cs 37 15 Balder.Silverlight
Warning 5 Field 'Balder.Controls.InstancingNodes.DataItemInfo.BoundingSphere' is never assigned to, and will always have its default value  C:\Balder\Source\Balder\Controls\InstancingNodes.cs 46 26 Balder.Silverlight
Warning 6 'Balder.Node.ManipulationStartedEvent' hides inherited member 'System.Windows.UIElement.ManipulationStartedEvent'. Use the new keyword if hiding was intended. C:\Balder\Source\Balder\Node.cs 88 76 Balder.Silverlight
Warning 7 'Balder.Node.ManipulationDeltaEvent' hides inherited member 'System.Windows.UIElement.ManipulationDeltaEvent'. Use the new keyword if hiding was intended. C:\Balder\Source\Balder\Node.cs 94 76 Balder.Silverlight
Warning 8 'Balder.Node.ManipulationStarted' hides inherited member 'System.Windows.UIElement.ManipulationStarted'. Use the new keyword if hiding was intended. C:\Balder\Source\Balder\Node.cs 99 46 Balder.Silverlight
Warning 9 'Balder.Node.ManipulationDelta' hides inherited member 'System.Windows.UIElement.ManipulationDelta'. Use the new keyword if hiding was intended. C:\Balder\Source\Balder\Node.cs 101 46 Balder.Silverlight
Warning 10 'Balder.Lighting.Light.IsEnabledProperty' hides inherited member 'System.Windows.Controls.Control.IsEnabledProperty'. Use the new keyword if hiding was intended. C:\Balder\Source\Balder\Lighting\Light.cs 110 48 Balder.Silverlight
Warning 11 'Balder.Lighting.Light.IsEnabled' hides inherited member 'System.Windows.Controls.Control.IsEnabled'. Use the new keyword if hiding was intended. C:\Balder\Source\Balder\Lighting\Light.cs 112 15 Balder.Silverlight
Warning 12 The field 'Balder.Node._position' is never used C:\Balder\Source\Balder\Node.cs 343 22 Balder.Silverlight
Warning 13 'Balder.Materials.Material.OpacityProperty' hides inherited member 'System.Windows.UIElement.OpacityProperty'. Use the new keyword if hiding was intended. C:\Balder\Source\Balder\Materials\Material.cs 345 53 Balder.Silverlight
Warning 14 The field 'Balder.Node._scale' is never used C:\Balder\Source\Balder\Node.cs 364 22 Balder.Silverlight
Warning 15 The field 'Balder.Node._rotation' is never used C:\Balder\Source\Balder\Node.cs 388 22 Balder.Silverlight
Warning 16 The event 'Balder.IntegrationTests.Silverlight.Stubs.Platform.BeforeStateChange' is never used C:\Balder\Source\Balder.IntegrationTests.Silverlight\Stubs\Platform.cs 32 36 Balder.IntegrationTests.Silverlight
Warning 17 The event 'Balder.IntegrationTests.Silverlight.Stubs.Platform.StateChanged' is never used C:\Balder\Source\Balder.IntegrationTests.Silverlight\Stubs\Platform.cs 33 36 Balder.IntegrationTests.Silverlight
Warning 18 Reference to type 'System.Diagnostics.Stopwatch' claims it is defined in 'c:\Program Files\Reference Assemblies\Microsoft\Framework\Silverlight\v5.0\system.dll', but it could not be found c:\Balder\Components\Silverlight\CThru.Silverlight.dll Balder.Tests.Silverlight
Warning 19 The variable 'fired' is assigned but its value is never used C:\Balder\Source\Balder.Tests\Notification\NotifyingObjectWeaverTests.cs 401 8 Balder.Tests.Silverlight
Warning 20 The variable 'fired' is assigned but its value is never used C:\Balder\Source\Balder.Tests\Notification\NotifyingObjectWeaverTests.cs 418 8 Balder.Tests.Silverlight

Anyway, overall:  I'm excited to get started with the fun bits in an upcoming block of free time.  (May be a while as I don't have many of those... heh)  I was blown away by how much was done 100% in XAML in the screencast.

Apr 26, 2011 at 10:17 AM

Can I just say... WOOOW..   That was awesome, I really love the feedback and the amount of details you provide with it, and yes very true on all of them.  Sorry to say, kinda, but the focus has been on the code and not the more "softer" values around the project, but seeing it in black and white like this sure helps get motivation to actually fix these things as well!

I think you're absolutely right, the project is in a state were it is very feature rich and has reached a stability level that based on input from others seems to be acceptable, some bugs are in there - but thats inevitable. 

If I can summarize a little bit what I think needs to be done : 

- Clean up the pages
- Get the nightly build server up and running that spits out binaries and documentation - and work more on documentation
- Get better information around the prerequisites to actually build things yourself, clean up repository for things like solution files and other things that are off
- Fix project files to target correct frameworks 


As for the point you had about tabs vs. spaces - I always thought VS defaults was tabs - but I guess that could be because I have a theme that I use that I've downloaded and always apply on a new install of VS. I can see your point here, but that really depends on the contributor, and if a contributor has tabs for other projects - switching is too painful in Visual Studio. So I'm not quite sure what would be the correct approach here. I'm very agnostic to the whole formatting thing. As for auto-formatting, completely agree with you - never fight that. I use R# and it together with VS is responsible for it all.. :)      StyleCop is IMO a bit too much - could be a turn off for many to go in and do stuff. But I'm not closing the door to it. 

Apr 26, 2011 at 5:54 PM

Thanks for taking the feedback constructively and replying so positively.  :)

Focus on code seems common to find in OSS projects - after all, it is "the fun part" to a lot of people who want to spend time on such a project.

I think I'd restate the fourth summary point as "Improve likelihood of solutions compiling error-free and warning-free for new users" but yeah, that looks about right for helping this be community-friendly.

I'm pretty sure vanilla VS installs start with tabs as default for C/C++ files but spaces as default for C# files... with Tools->Options->TextEditor->AllLanguages blank to allow for language-specific settigns.  At least that's what I have here and at both work machines and I try to make a point not to change any VS defaults unless a project requires it.

As for StyleCop, yeah that's why it's so customizable with settings files that can check in so everyone ends up with the same settings, if they're using it.  The value in using something like it increases with the number of distinct contributors you have with different ideas of how code should be styled, but it doesn't have to be treated as something like a "check-in rule" - anyway I might be biased seeing as I like the StyleCop OSS project enough to have contributed to fixing their first time user experience  :)