How should we structure the documentation?

Topics: Documentation
Coordinator
Jul 1, 2010 at 6:36 PM
Edited Jul 1, 2010 at 10:03 PM

We planned to spend some time to prepare the documentations before the first beta release (by end of July 2010). As we are still in the early stage, it would be a good time to look into the user scenarios and design a high level structure/flow of the documentation. Following is the initial draft structure of the documentation section.

Please feel free to suggest adding or restructuring any sections.

  • Getting Started  
    • Walkthrough on:       
      • how to setup (install necessary tools)
      • creating a simple application and use the gesture features
      • creating your own gesture
      • writing a unit test to validate a custom defined gesture
      • how to run the application on different devices (i.e. SMART Tabletop, Surface)
      • how to add support for a new device
    • An overview of the project site
      • How the documentation is organized
      • Where to get the latest stable build, nightly build, latest source etc.
  • API Documentation
    • Detailed description of the API (i.e. description of public methods, functionalities etc)
    • Feature list (i.e. list of primitive-conditions, return types, predefined gestures)

  • Architecture Overview
    • Describes the system architecture.
      Comparatively less implementation details and more on the architecture design

 

Note: Some of the sections may include video or live demo as necessary.

Oct 30, 2010 at 2:18 AM

Hi Shahed,

It would be great if the code you include in your documentation contains comments. Its not always clear what each method does (for instance, the ToGDL method).

Also, I would appreciate explanations of what the syntax definitions of conditions, etc mean.

 

Good luck

Coordinator
Oct 30, 2010 at 2:26 AM

Hi Maha,

Thank you for using the discussion board. Point taken. I will look into the documentations issues.

However, all public methods in framework.dll has method level comments. You can use the IDE features (e.g. hover mouse over a method name...) to see them.

GDL is a common term used widely across the toolkit. Its an acronym for Gesture Definition Language. Like the ToString() method which converts an object value into string, ToGDL() converts the primitive condition object to GDL which is a string.