resources: Tutorial Project Improvements

* implemented "user study" feedback
2015-11-17 10:54:56 +01:00
parent 8f0213e18c
commit 42afbce300
14 changed files with 87 additions and 49 deletions
@@ -6,7 +6,7 @@

 //------------------------------------------------------------------------------
 //
-// THE CODE TUTORIAL
+// 1 - THE CODE TUTORIAL
 //  As you already know the code view displays the snippets of code that are 
 //  related to your currently active symbol. These snippets show the relevant 
 //  lines in combination with some context. 
@@ -6,13 +6,8 @@

 //------------------------------------------------------------------------------
 //
-// MANAGING CONTEXT
-//  At this stage you see the whole file. For a shortcut to get here you also
-//  could have clicked the maximize button at the title bar of the box that
-//  contains this snippet. It is inactive now because the file is already shown
-//  as a whole. Before you start experimenting with the other buttons, remember
-//  that you can click the maximize buttons to get back here and continue
-//  reading.
+// 5 - NO MORE CONTEXT
+//  At this stage you see the entire file and no more context can be expanded.
 //  For the final part of this introduction please have a look at where the
 //  "unrelated_but_very_important()" function is used.
 //
@@ -31,7 +26,7 @@ int calculate(int (*problem)())

 //------------------------------------------------------------------------------
 //
-// MORE CONTEXT
+// 4 - MORE CONTEXT
 //  Who would have expected such a simple question?
 //  Note that expanding the view didn't change the active symbol. You can
 //  proceed expanding the view until you hit the level of the file scope.
@@ -46,16 +41,17 @@ void deep_thought()

 //------------------------------------------------------------------------------
 //
-// CONTEXT
+// 2 - CONTEXT
 //  We just talked about Coati providing context to the important lines of code.
 //  But it feels like something is missing here. What is "the_question"? And
 //  where does it come from?
 //
-// EXPANDING TO SCOPES
-//  Do you see first line of this snippet? It has no line number and says
-//  "deep_thought". Actually this is the name of the scope that encapsulates the
-//  snippet. By clicking that line you can tell Coati to expand the view to show
-//  the whole scope. Give it a try!
+// 3 - EXPANDING TO SCOPES
+//  Do you see first line of this snippet? I mean the one that has just two dots 
+//  as line number and reads "deep_thought". Actually that's the name of the  
+//  function's scope that encapsulates the snippet. By clicking that line you 
+//  can tell Coati to expand the view to show the entire scope. 
+//  Give it a try!
 //
 //------------------------------------------------------------------------------
 	int the_answer = calculate(the_question);
@@ -7,13 +7,17 @@

 //------------------------------------------------------------------------------
 //
-// SNIPPETS AND FILES
-//  It looks like this function is called in two different snippets. When two
-//  different snippets are located in the same file they share a common file
-//  view but each of them depicts the name of its own parent's scope.
-//  If you want to show the lines in between these two snippets you can either
-//  expand the upper snippet's scope to show the whole file or you can tell the
-//  lower snippet to reveal its scope.
+// 6 - SNIPPETS AND FILES
+//  It looks like this function is called in two different places inside the 
+//  same file. When two different snippets are located in the same file they 
+//  share a single file box. The line numbers to the left indicate where each of 
+//  these snippets is located inside the file.
+//
+// 7 - MERGING SNIPPETS
+//  The top line of each snippet shows the name of its own parent's scope.
+//  If you want to show the lines in between the two snippets below you can 
+//  either expand the upper snippet's scope to show the whole file or you can 
+//  tell the lower snippet to reveal its scope.
 //  Try one of these approaches now.
 //
 //------------------------------------------------------------------------------
@@ -25,24 +29,25 @@ void function_with_snippets()

 //------------------------------------------------------------------------------
 //
-// YOU FOUND THE HIDDEN COMMENT
+// 8 - YOU FOUND THE HIDDEN COMMENT
 //  Well done! As you see Coati merged the two snippets from before because
 //  expanding a scope would have caused them to overlap. That's all for the code
-//  view.
+//  view tutorial.
 //
-// EDIT YOUR CODE
+// 9 - EDIT YOUR CODE
 //  In case you wondered if you can edit your code using Coati: You can't. Coati
 //  is designed for code exploration, not as a text editor or an IDE. But there
 //  is a chance that Coati can talk to your favourite editor (that you already
 //  know how to operate) via plugin. For more information about available
-//  plugins please take a look at the Coati User Manual.
+//  plugins please take a look at Coati's user manual.
 //
 //  We hope you enjoyed this tutorial. You can follow the call below to get back
 //  to the central hub.
 //
 // P.S.
-//  You can also click the file name above to activate the file's node in case
-//  you want to explore your include hierarchy.
+//  You can also click the file name above (i guess you need to scroll up a 
+//  little bit) to activate the file's node in case you want to explore your 
+//  include hierarchy.
 //
 //------------------------------------------------------------------------------

@@ -6,13 +6,13 @@

 //------------------------------------------------------------------------------
 //
-// THE GRAPH TUTORIAL
+// 1 - THE GRAPH TUTORIAL
 //  In Coati's default window layout the graph is shown to the left, next to the
 //  code. It displays the structure of your project where all named symbols are
 //  nodes and all relations are edges. Like the code view it shows only the
 //  currently active symbol and all the incoming and outgoing dependencies.
 //
-// HOW DO I NAVIGATE THE GRAPH
+// 2 - HOW DO I NAVIGATE THE GRAPH
 //  You can activate a new symbol by left-clicking on the node you are 
 //  interested in. For example: to find out where the function 
 //  "where_am_i_called()" is called get over to the graph and click that 
@@ -6,7 +6,7 @@

 //------------------------------------------------------------------------------
 //
-// WELL DONE
+// 3 - WELL DONE
 //  You activated a node and both, the graph and the code view have been updated
 //  accordingly.
 //  Note that even though Coati provides a graph view it does not remove the
@@ -15,13 +15,13 @@
 //  interested in you should still consider the code view to actually read up on
 //  all the important details.
 //
-// HIDDEN ELEMENTS
+// 4 - HIDDEN ELEMENTS
 //  In order not to flood you with information the graph is hiding a lot of
 //  elements. Do you see the "ClassWithHiddenMembers" for example? It actually
 //  contains more members than you currently see. Members that are not important
-//  for the current context are hidden. Nevertheless you can reveal by clicking
-//  the arrow next the the class name.
-//  Try that now.
+//  for the current context are hidden. Nevertheless you can reveal them by 
+//  clicking the arrow next the the class name. Try that now and read those 
+//  members' names.
 //
 //------------------------------------------------------------------------------

@@ -51,7 +51,7 @@ public:

 //------------------------------------------------------------------------------
 //
-// RELATIONS
+// 5 - RELATIONS
 //  As you see in the graph, this member is accessed at quite some places
 //  throughout the code base. Lets say you wonder what code causes the edge
 //  between "reading" and "this_last_member" to appear. What will happen if you
@@ -18,13 +18,14 @@ public:
 	}
 //------------------------------------------------------------------------------
 //
-// FOCUSING EDGES
+// 6 - FOCUSING EDGES
 //  Even though Coati doesn't allow to activate an edge, you can still focus on
 //  edges. This doesn't change the currently active symbol (which would cause 
 //  Coati to hide everything but the edge). Instead Coati just highlights the
 //  relation's location in the code and scrolls you there, so you don't lose 
 //  context.
-//  Try to activate some more relation.
+//  Try to activate an edge that comes from the "ConsumerOfTheLastMember" class.
+//  Which one you pick doesn't really matter for this tutorial.
 //
 //------------------------------------------------------------------------------
 	void reading()
@@ -15,7 +15,7 @@ public:

 //------------------------------------------------------------------------------
 //
-// THAT'S IT
+// 7 - THAT'S IT
 //  You completed the tutorial on the graph view. There is still more to learn
 //  but I guess you will figure it out on your own. One last thing: If you see
 //  an element with a hatched background please call us. It's a runaway!
@@ -6,7 +6,7 @@

 //------------------------------------------------------------------------------
 //
-// THE SEARCH TUTORIAL
+// 1 - THE SEARCH TUTORIAL
 //  If you haven't messed up anything yet, you'll find the search bar to the
 //  upper left of Coati's user interface. Initially it shows the name of the
 //  currently active symbol.
@@ -6,7 +6,7 @@

 //------------------------------------------------------------------------------
 //
-// THE AUTOCOMPLETION
+// 2 - THE AUTOCOMPLETION
 //  I hope you have been lazy enough to not enter the whole string from start to
 //  finish. So you already noticed Coati's autocompletion box.
 //  While you enter your search request Coati already tries to find a subset of
@@ -6,7 +6,7 @@

 //------------------------------------------------------------------------------
 //
-// FUZZY MATCHING
+// 3 - FUZZY MATCHING
 //  While looking for matching symbols the search bar does not only consider
 //  strict matches to the entered substring. Instead it uses a more fuzzy
 //  approach. This is really helpful when you only have a rough idea of what the
@@ -6,23 +6,23 @@

 //------------------------------------------------------------------------------
 //
-// WHAT ARE THE OTHER BUTTONS?
+// 4 - WHAT ARE THE OTHER BUTTONS?
 //  Well done. Lets get over the other buttons left to the search bar really
 //  quick.
 //
-// UNDO AND REDO
+// 5 - UNDO AND REDO
 //  You can use the buttons to the very left to undo and redo your actions. This
 //  may seem odd since Coati doesn't include any features to actually change
 //  code. Instead Coati offers these buttons to help you navigate. So they
 //  really come in handy in case you ask yourself something like "How did I end
 //  up here?"
 //
-// REFRESH
+// 6 - REFRESH
 //  The next button allows you to refresh you project in case you changed some
 //  of your code. The second button toggels the auto-refresh option. When
 //  enabled Coati refreshes your project every time it's window gets focused.
 //
-// WHAT'S NEXT?
+// 7 - WHAT'S NEXT?
 //  Instead of the class activate the struct with the same name as before.
 //
 //------------------------------------------------------------------------------
@@ -6,7 +6,7 @@

 //------------------------------------------------------------------------------
 //
-// CONGRATULATONS
+// 8 - CONGRATULATONS
 //  You have completed the challenge of search.
 //  Oh, I almost forgot: You can only find nodes such as symbols via the search 
 //  bar. It doesn't allow you to find edges like calls or inheritance. At least
@@ -0,0 +1,33 @@
+#ifndef START_EXPLORING_H
+#define START_EXPLORING_H
+
+
+#include "utility.h"
+
+//------------------------------------------------------------------------------
+//
+// FURTHER EXPLORATION
+//  If you completed all the other tutorials you might want to put your new 
+//  skills to use and do some exploration on your own. 
+//  Here comes the bad news: Even though this tutorial contains some code that 
+//  would compile, the code doesn't make much sense. So trying to explore this 
+//  project any further would be rather unproductive.
+//  The good news is: In addition to this tutorial Coati also ships with a real
+//  example project that implements the game Tic-Tac-Toe! You can open the 
+//  project via the "Project -> Recent Projects" menu.
+//  You can also start exploring your own projects by creating a new Coati 
+//  project where you can add all your source and include paths.
+//
+//------------------------------------------------------------------------------
+
+class StartExploring
+{
+public:
+	StartExploring()
+	{
+	}
+};
+
+
+#endif // START_EXPLORING_H
+
@@ -2,9 +2,10 @@
 #define THE_CENTRAL_HUB_H


-#include "code_tutorial_1.h"
-#include "graph_tutorial_1.h"
 #include "search_tutorial_1.h"
+#include "graph_tutorial_1.h"
+#include "code_tutorial_1.h"
+#include "start_exploring.h"

 //------------------------------------------------------------------------------
 //
@@ -22,6 +23,8 @@ void the_central_hub()
 	SearchTutorial* the_challenge_of_search;
 	GraphTutorial* reading_the_map;
 	CodeTutorial* explore_the_details;
+
+	StartExploring* going_beyond_this_tutorial;
 }