Ticket	Summary	Owner	Status	Type	Component	Priority	Effort	Importance
#1535	GLOBAL_SPEC_STRUCTURE_R1	kyli	closed	planned_task	GLOBAL_SPECIFICATION_ARTIFACTS	3	2	90
Reported by Astea, 4 years ago.
Description	wiki page: GLOBAL_SPEC_STRUCTURE_R1 - effort: 2d
Analysis_owners	deyan
Analysis_reviewers	todor
Analysis_score	3.5
Design_owners	kyli
Design_reviewers	todor
Design_score	3.5
Imp._owners	kyli
Imp._reviewers	veliko
Imp._score	3.5
Test_score	0

Analysis

Overview

Current GLOBAL_SPEC_STRUCTURE contains obsolete information. Redesign and maintain it. Specify a consistent gui elements concept.

Task requirements

• Schedule a discussion about application behavior, create a wiki page containing the results of the discussion (GUI elements and user interactions).
  • Behavior similar to Sophie 1
  • New things
• Review GLOBAL_SPEC_STRUCTURE
• Divide the "specification" term into "specification" and "user documentation"
  • Point user documentation as specification task
  • Link user doc tasks from ITERATION_02b
• Create structure for user documentation and fill it with corresponding elements.
• Decide where do keyboard shortcuts belong (and other similar elements if any will be supported - for example mouse gestures.)
• Review existing spreadsheet ​http://spreadsheets.google.com/ccc?key=p-0Oq38E1aysuTs69KE68Nw and improve it's structure if needed

Task result

Improved GLOBAL_SPEC_STRUCTURE

Implementation idea

Create a wiki page to store the discussion results.

Related

GLOBAL_SPEC_STRUCTURE_R0
GLOBAL_SPEC_STRUCTURE
​http://spreadsheets.google.com/ccc?key=p-0Oq38E1aysuTs69KE68Nw

How to demo

Show ​http://spreadsheets.google.com/ccc?key=p-0Oq38E1aysuTs69KE68Nw , explain the User Documentation, keyboard shortcuts.

Design

• Revise the current table in GLOBAL_SPEC_STRUCTURE:
  • Change the diagrams link: ​svn://sophie2.org/sophie2/trunk/sophie2-platform/doc/spec-diagrams
  • Fix the "not available" links: the folders must be linked with their path in the repository, and the missing documents must be copied from the old repository and linked.
  • We need a specification for the user documentation - its structure, its content.
    • Link the user_doc tasks until now, which have analyses (the analyses are actually specifications).
    • Specify where the documentation will be stored.
  • Replace the table with a structured text (or several smaller tables - which is better) - this way longer descriptions/explanations could be made without affecting the good look of the document.
• Revise the google spreadsheet:
  • Make a better outlook of the document - the tree structure is not good; the column descriptions could be in italics in order to distinguish them from the content.
  • Discuss the name of the spreadsheet - sophie2-gui-elements is not correct, since it contains DND table, too. A better name would be "sophie2-user-interactions"
  • Acording to the Sophie2 master specification, there will be undescribed user interactions, like:
    • keyboard shortcuts: create a sheet in the existing document for this, called "Keyboard Shortcuts". Make a simple outline there and fill it in with the shortcuts, described in the specification.
    • Every other interaction must be put in the same document (for example, the Special keyboard interactions, mouse gestures, etc.)
  • Updating information on the current tables is part of another task.
• All discussions' results would be better to be stored in the existing GLOBAL_SPEC_STRUCTURE and applied to the corresponding documents.

Implementation

Done as described in the Design section. Notes:

• The long links were replaced with just "link" and no may new specification artifacts are expected to appear. So, replacing the table with structured text was not neccessary.
• The structure of the sophie2-gui-elements sheet was not changed, since the task was overtimed and taking care of the content of the document is part of another task.

Testing

Comments

In the next revision of the task, it would be good to split the "gui elements" sheet in categories (maybe different sheet for each), since with specification growing it may become unreadable. --kyli