Update: I just read this post in my news aggregator and some of the formatting didn't make the translation. For best evaluation you should probably look at this post in your web browser at http://blog.retrosight.com/DocumentationWhichDoYouLikeBetter.aspx.

I'm willing to bet Jeff Atwood has an opinion about this given his recent post Escaping From Gilligan's Island. We've been having an internal debate on how to best document steps to create applications -- mostly so folks find it easy to get it right the first time (hence the hat tip to Jeff's post).

I'd like to get your opinion on which of the following set of steps you find easier to follow (A or B) -- these steps are based on the Visual C# 2005 Express Edition Integrated Design Environment if you would like to try them out for real.

A - Create a strong name key file and add to the project assembly

1.       In the Solution Explorer pane, right-click the project and click Properties.

2.       Click the Signing tab, select the Sign the assembly check box.

3.       In the Choose a strong name key file list, click New.

4.       In the Key file name box, type a name.

5.       Optionally, select the Protect my key file with a password check box and enter a password for the key file.

6.       Click OK.

7.       On the File menu, click Save All.

8.       On the Build menu, click Build Solution to build the project assembly with the strong name key file.

B - Create a strong name key file and add to the project assembly

1.       Select the project in the Solution Explorer pane.

2.       Select View > Property Pages from the menu.

3.       In the Properties window:

a.       Select the Signing tab.

b.      Check the box labeled Sign the assembly.

c.       Click on the Choose a strong name key file drop-down list and select <New...>.

d.      In the Create Strong Name Key dialog:

                                                               i.      Enter a key file name

                                                             ii.      Optionally provide a password for the key file.

                                                            iii.      Click OK.

4.       Select File > Save All from the menu.

5.       Select Build > Build Solution from the menu to build the project assembly with the strong name key file.



Categories: Media Center SDK Code Sample | Software Development Kit | Windows Media Center | Comments [7] | # | Posted on Friday, June 22, 2007 5:53:03 AM (GMT Daylight Time, UTC+01:00)   
Friday, June 22, 2007 6:28:52 AM (GMT Daylight Time, UTC+01:00)
I'm a hierarchical kind of guy so I prefer B. It gives me more of a higher level view of where I'm at for a particular step in the overall procedure.
Friday, June 22, 2007 6:47:20 AM (GMT Daylight Time, UTC+01:00)
B is for sure easier on the eyes.
Ray
Friday, June 22, 2007 7:56:12 AM (GMT Daylight Time, UTC+01:00)
I agree with both Keith and Ray, B is an easier set of steps to follow
David Wright
Friday, June 22, 2007 10:31:42 AM (GMT Daylight Time, UTC+01:00)
Chalk up another vote for B. :)
Theodor Kleynhans
Friday, June 22, 2007 3:10:14 PM (GMT Daylight Time, UTC+01:00)
Overall, (B) works better because the indentation conveys some context of how deep into the menu/window structure you should be; (A) conveys none of that context, so you end up having to pay closer attention to whether you've been told to change windows/menus.

However, I know (having done this myself) that the "View > Property Pages" notation is simply a cheat by the writer, and that it expects familiarity with the UI that isn't there for the folks that need the help instructions most.

While an instruction like (A)(4) seems redundant compared to (B)(3)(d)(i), that is easily remedied by ensuring that it doesn't just end with "type a name" but rather give the user an idea of what would constitute a decent or appropriate name, e.g. "type a name such as the name of your product" (if that's appropriate) or "type a name (anything will do as this is a description just for the developer)" (if that's more accurate).

Finally, the only reason why (B)(3)(d)(ii) is preferable over (A)(5) is because there are too many undifferentiated words interrupting what should be a simple instruction. (A)(5) at its heart is intended to indicate "select the checkbox" as in "select the checkbox labelled Protect my key file with a password". The approach of Bolding the phrase "Protect my key file with a password" where it currently exists will make it *easier* to know what's a label and what's the core instruction, but it's still breaking up the simple instruction into a complex sentence that the reader has to keep in their head all at once.
Saturday, June 23, 2007 7:51:45 AM (GMT Daylight Time, UTC+01:00)
B is of course much easier to read/follow both due to it being hierachical - but also because the steps a broken down further. (and if you are jumping back in half way through - example A mixes multiple actions into one sentance - so there's no clear reentry point).

However - B won't read well if the actions are long winded (and sentacnes wrap accross more than one line).

(Much) More important than A+B of course is C - that the documentation is written clearly and covers unexexpected situations (not just the perfect scenario).
Friday, June 29, 2007 2:18:04 AM (GMT Daylight Time, UTC+01:00)
Definitely B. It is much easier to follow especially when switching (alt-tab) between apps. I also like the Menu Item > SubMenu > SubSubMenu notation better and it follows Microsoft's notation standard (KB site).
Comments are closed.
Search
Sign In | All Content © 2010 Charlie Owen

This is a personal weblog. The opinions expressed here represent my own and not those of my employer.


Powered by newtelligence dasBlog 2.3.9074.18820