Ticket	Summary	Owner	Status	Type	Component	Priority	Effort	Importance
#1589	UNPLANNED_USER_DOC_STRUCTURE_R0	danvisel	closed	unplanned_task	SOPHIE_END_PRODUCT	major	2	90
Reported by deyan, 4 years ago.
Description	UNPLANNED_USER_DOC_STRUCTURE_R0
Analysis_owners	danvisel
Analysis_reviewers	kyli,deyan
Analysis_score	3.5
Design_owners	danvisel
Design_reviewers	pap
Design_score	3.5
Imp._owners	danvisel
Imp._reviewers	pap,pap
Imp._score	4
Test_score	0

Analysis

This is the structure for user documentation on the Sophie 2 website.

Overview

This is a numbered outline that explains what will be in the Sophie 2 documentation and where.

Task requirements

• The user documentation will eventually need to provide information for users of Sophie Author, Sophie Reader, and Sophie Server; eventually, these need to become three separate documents (although interconnected). For now, I'm going to start with a single document for Sophie with the idea that this is going to be split into sections.

• There needs to be a logical page-naming structure if this is to work as a wiki; this should be extensible.

• There needs to be a (possibly rudimentary) style guide covering how images are handled, how numbering is handled, similar issues. Style guide isn't exposed to the public.

Task result

For this task, there will be a sample outline (as a page in the wiki) and a sample style guide (as a page in the wiki). From this we can start work on real documentation.

Implementation idea

Using Sophie 1.0 documentation outline.

Related

UNPLANNED_USER_DOC_SAMPLE_R0 (sample of user documentation)

How to demo

Look at the outline and style guide.

Design

User documentation will be online in the Trac wiki until it moves to the SCS. To start, it will follow the outline for the Sophie 1.0 documentation (online here in PDF form: ​http://sophieproject.cntv.usc.edu/files/SophieHelp1.0.3.pdf ). Major sections (e.g. 2. Working with Sophie, 3. Working with Frames) will each get a page with an introduction and a table of contents. Subsections in each section (e.g. 2.1. Sophie's Interface, 2.2. Halos & Huds) will each get their own page.

As Sophie Reader and Sophie Server begin to exist as separate applications, each will get their own separate documentation so that users can learn about each separately if they want to.

For a sample outline, see here: UNPLANNED_USER_DOC_STRUCTURE/Outline

For a sample style guide, see here: UNPLANNED_USER_DOC_STRUCTURE/StyleGuide (for internal reference)

This will be done entirely in the wiki; no additional tools will be needed.

Implementation

Sophie 1.0 documentation is here: ​http://sophieproject.cntv.usc.edu/files/SophieHelp1.0.3.pdf

For a sample outline, see here: UNPLANNED_USER_DOC_STRUCTURE/Outline

For a sample style guide, see here: UNPLANNED_USER_DOC_STRUCTURE/StyleGuide

Iteration 03 Release 1 documentation is here: ITERATION_03/Release/UserDocumentation. This follows the outline in UNPLANNED_USER_DOC_STRUCTURE/Outline; the page-naming conventions were changed at Pap's request. A section on pre-release builds of Sophie was added for installation instructions and dealing with things like the Inspector that won't be in the final releases. More rules are being added to the style guide as they arise.

Testing

Comments

Outline is essentially as it was in Sophie 1.0 - no changes have been made yet.