| <?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/></head><body><h1 id="IntentExternalDocumentationsupport">Intent : External Documentation support</h1><h2 id="Overview">Overview</h2><p>For the time being, the only way to type Intent documentation is through the Intent editor.<br/>However, synchronization and authoring capabilities of Intent are 2 distinct features.</p><p>It makes perfect sense to only use the synchronization capabilities of Intent, and rely on other formats to author and store the documentation (Textile files, Wiki pages, Open-office documents...).</p><p>This document specifies how Intent should handle such external documentation files.</p><h2 id="Concepts">Concepts</h2><p>Before detailing the end-user scenario, we must define the following concepts.</p><h3 id="ExternalDocument">External Document</h3><p>A piece of documentation which is not stored inside an Intent repository (can be a textile file in the workspace, a Wiki page, an open-office document...).</p><h3 id="LinkstowardExternaldocuments">Links toward External documents</h3><p>We will distinguish 2 kinds of link from the Intent document to an <a href="#ExternalDocument">external document</a> : <a href="#Fulllinks">Full Links</a> and <a href="#Reflinks">Ref Links</a>.</p><p><strong>Such links will be displayed in the Project explorer (contrary to other instructions).</strong> This will ease operations on these links (Drag and Drop of technical artifacts, link with the <a href="#DocumentationAttachmentsView">Documentation Attachments View</a> ...).</p><h4 id="Reflinks">Ref links</h4><p>A ref link is composed of a simple URI indicating the <a href="#ExternalDocument">external document</a> location (e.g. <em>http://my.Wiki.org/myWikiPage</em>, <em>platform:/resource/myProject/myTextileFile.textile</em>, <em>file:///PATH_ON_DISK/myOpenOfficeDocument.doc</em>). It will also contain a list of technical artifacts related to this external document.</p><p>It will be used for <a href="#ExternalDocument">external document</a> that we cannot represent as EMF Models (see <a href="#Fulllinks">Full Links definition</a> ).</p><h4 id="Fulllinks">Full links</h4><p>A Full link is a <a href="#Reflinks">Ref link</a> containing the content of the referenced <a href="#ExternalDocument">external document</a> as an instance of the Markup metamodel.</p><p>For instance, the default markup parser already allows to represent any textile file as an instance of the Markup metamodel. So if we reference a textile file as an <a href="#ExternalDocument">external document</a> , Intent will be able to parse the document and store it as an EMF model.</p><p>Notice that here it will not contain a list but a map of technical artifacts, associating each precise piece of documentation in the external document (e.g. a Wikitext section or a Wiki paragraph/image) with a set of technical artifacts.</p><h3 id="SynchronizationbetweenIntentdocumentandExternaldocuments">Synchronization between Intent document and External documents</h3><p>As the documentation is no longer exclusively stored in the Intent repository and authored through the Intent editor, the question of the synchronization between Intent documentation and external document is raised.</p><h4 id="ForExternaldocumentsreferencedthroughReflinks">For External documents referenced through Ref links</h4><p>As Intent has no information about the content of these documents, modifying them will not raise any synchronization issue.</p><h4 id="ForExternaldocumentsreferencedthroughFulllinks">For External documents referenced through Full links</h4><p>As Intent stores the content of such document, we have 2 possible way of handling a modification on them: <a href="#AutomaticChangeIntegration">Automatic Change Integration</a> and <a href="#InteractiveChangeIntegration">Interactive Change Integration</a> .<br/>As each mode brings benefits and drawbacks according to the use case, it should be possible for the end-user to configure the chosen mode file-by-file or file type-by-file type.</p><h5 id="AutomaticChangeIntegration">Automatic Change Integration</h5><p>In that mode, whenever an external file is modified, we silently apply the changes on the corresponding <a href="#Fulllinks">EMF copy</a>.</p><h5 id="InteractiveChangeIntegration">Interactive Change Integration</h5><p>In that mode, whenever an external file is modified, we raise a synchronization issue indicating that the document has changed. As with a technical artifact-related synchronization issue, changes can be visualized graphically using EMF Compare dialogs. The end-user will have to accept manually the change to update the <a href="#Fulllinks">EMF copy</a> .</p><h2 id="EnduserScenarios">End-user Scenarios</h2><p>We will follow step-by-step a scenario in which the end-user wants to use 2 different Wikis (each containing several pages) and an Open-office file as external documents,and still using Intent for some sections.</p><h3 id="Intentprojectcreation">Intent project creation</h3><p>The Intent project is created as usual.</p><h3 id="ReferencingWikipages">Referencing Wiki pages</h3><h4 id="Scenario01referencingaWikipagethroughtheIntenteditor">Scenario 01: referencing a Wiki page through the Intent editor</h4><p><strong>As a</strong> documentation writer<br/><strong>I want to</strong> reference a Wiki page in my documentation<br/><strong>So that</strong> I can link this Wiki page with technical artifacts<br/><strong>Given</strong> an empty Intent project and a Wiki page<br/><strong>When</strong></p><ul><li>I type <strong>@ref "<em>WIKI_PAGE_URI</em>"</strong></li></ul><p><strong>Then</strong></p><ul><li>Intent creates a <a href="#Fulllinks">Full link</a> in the current Intent Structured Element (Document/Chapter/Section)</li></ul><p>Notice that the end-user will be notified if a new sub-page is added to the referenced Wiki page (see <a href="#Wikipagesaddition">the corresponding scenario</a> ).</p><h4 id="Scenario02referencingoneorseveralWikipagesthroughIntentUI">Scenario 02: referencing one or several Wiki page(s) through Intent UI</h4><p><strong>As a</strong> documentation writer<br/><strong>I want to</strong> reference many pages from a Wiki in my documentation<br/><strong>So that</strong> I can link these Wiki pages with technical artifacts<br/><strong>Given</strong> an empty Intent project and a list of Wiki pages I want to reference<br/><strong>When</strong></p><ul><li>I right-click in the current editor, the Intent project or one of the Intent structured element (in the Project explorer view) and select the <em>"Add links toward other documents"</em> Action</li></ul><p><strong>Then</strong></p><ul><li>The following wizard is opened : </li></ul><p><img border="0" src="external_documents_link_wizard01.png"/></p><ul><li>As soon I enter a Wiki page URL, this page and all sub-pages are listed below</li><li>Once I’ve selected the target Intent Element (single-valued) and the list of external documents to reference, Intent creates <a href="#Fulllinks">Full links</a> in the selected element (<strong>@ref "<em>SELECTED_WIKI_PAGE_URI</em>"</strong>)</li></ul><h3 id="Referencingopenofficedocuments">Referencing open-office documents</h3><h4 id="Scenario03referencinganOpenOfficedocumentthroughtheIntenteditor">Scenario 03: referencing an Open Office document through the Intent editor</h4><p><strong>As a</strong> documentation writer<br/><strong>I want to</strong> reference an Open Office document in my documentation<br/><strong>So that</strong> I can link this Open Office document with technical artifacts<br/><strong>Given</strong> an empty Intent project and an Open Office document<br/><strong>When</strong></p><ul><li>I type <strong>@ref "<em>file:///_DOCUMENT_ABSOLUTE_LOCATION</em>"</strong> or <strong>@ref "<em>DOCUMENT_PATH_IN_WORKSPACE</em>"</strong></li></ul><p><strong>Then</strong></p><ul><li>Intent creates a <a href="#Reflinks">Ref link</a> in the current Intent Structured Element (Document/Chapter/Section)</li></ul><h4 id="Scenario04referencingOpenOfficedocumentsthroughaIntentUI">Scenario 04: referencing Open Office documents through a Intent UI</h4><p><strong>As a</strong> documentation writer<br/><strong>I want to</strong> reference many Open Office documents in my documentation<br/><strong>So that</strong> I can link theseOpen Office documents with technical artifacts<br/><strong>Given</strong> an empty Intent project and a list of Open Office documents I want to reference<br/><strong>When</strong></p><ul><li>I right-click in the current editor, the Intent project or one of the Intent structured element (in the Project explorer view) and select the <em>"Add links toward other documents"</em> Action</li></ul><p><strong>Then</strong></p><ul><li>The following wizard is opened : </li></ul><p><img border="0" src="external_documents_link_wizard02.png"/></p><ul><li>As soon I enter a folder or a document absolute path (possibly using «Browse File System...») or workspace relative path (possibly using «Browse Workspace...») , the files contained in the folder or the file itself are displayed below</li><li>Once I’ve selected the target Intent Element (single-valued) and the list of external documents to reference, Intent creates <a href="#Reflinks">Ref link</a> in the selected element (<strong>@ref "<em>SELECTED_DOCUMENT_PATH</em>"</strong>)</li></ul><h3 id="Settingupchangeintegrationmode">Setting-up change integration mode</h3><p>For any external document referenced through a <a href="#Fulllinks">Full link</a> , the end-user will be able to change the change integration mode (whether <a href="#AutomaticChangeIntegration">Automatic</a> or <a href="#InteractiveChangeIntegration">Interactive</a> ).<br/>The change integration can be configured for each link type, and/or per external document link.</p><p>This can be done by:</p><ul><li>adding <strong>change=SILENT</strong> or <strong>change=INTERACTIVE</strong> at the end of the @ref instruction</li><li>right-clicking on an Intent Project and select the <em>"Configure Change integration"</em> action (which will open the <a href="#ChangeIntegrationWizard">Change Integration Wizard</a> )</li><li>right-clicking on a Full link and select the <em>"Configure Change integration"</em> action (which will open the <a href="#ChangeIntegrationWizard">Change Integration Wizard</a> )</li></ul><h4 id="ChangeIntegrationWizard">Change Integration Wizard</h4><p>This change integration Wizard allows to define the Default rules (per document type):<br/><img border="0" src="change_integration_wizard01.png"/></p><p>And specific rules (per document):<br/><img border="0" src="change_integration_wizard02.png"/></p><h4 id="Scenario05ConfigureChangeIntegrationonallWikifilesthroughthewizard">Scenario 05: Configure Change Integration on all Wiki files through the wizard</h4><p><strong>As a</strong> documentation writer<br/><strong>I want to</strong> configure the way changes on Wiki file are integrated<br/><strong>So that</strong> I do not have synchronization issues when modifying them (changes are automatically integrated)<br/><strong>Given</strong> an Intent document referencing (through <a href="Fulllinks)">Full links</a> several Wiki pages<br/><strong>When</strong></p><ul><li>right-clicking on an Intent Project and select the <em>"Configure Change integration"</em> action (which will open the <a href="#ChangeIntegrationWizard">Change Integration Wizard</a> )</li></ul><p><strong>Then</strong></p><ul><li>The following wizard is opened : </li></ul><p><img border="0" src="change_integration_wizard01.png"/></p><ul><li>I can modify the default integration mode for all Wiki files (<strong>Automatic</strong>)</li></ul><h4 id="Scenario06ConfigureChangeIntegrationonasingleWikifileusingtheIntenteditor">Scenario 06: Configure Change Integration on a single Wiki file using the Intent editor</h4><p>Notice that this could be done through the Change Integration Wizard":#ChangeIntegrationWizard (<em>"Specific Rules"</em> tab).</p><p><strong>As a</strong> documentation writer<br/><strong>I want to</strong> configure the way changes on a specific Wiki file («Architectural overview» on Intent Wiki) are integrated<br/><strong>So that</strong> I have synchronization issues when modifying this page (changes are NOT automatically integrated)<br/><strong>Given</strong> an Intent document referencing (through <a href="Fulllinks)">Full links</a> a page on Intent Wiki («Architectural overview»)<br/><strong>When</strong></p><ul><li>editing the <strong>@ref</strong> instruction by adding <strong>change=INTERACTIVE</strong> at the end</li></ul><p><strong>Then</strong></p><ul><li>the change integration is set to Interactive for this <a href="Fulllinks">Full link</a></li></ul><h3 id="Livingwithchangesindocumentation">Living with changes in documentation</h3><h4 id="Minormodifications">Minor modifications</h4><p>Whenever an external documentation is updated, 3 cases can occur:</p><ul><li>the external document is referenced through a <a href="#Reflinks">Ref Link</a> : no changes</li><li>the external document is referenced through a <a href="#Fulllinks">Full Link</a> with an <a href="#AutomaticChangeIntegration">Automatic Change Integration</a> : the new content is silently merged into the link</li><li>the external document is referenced through a <a href="#Fulllinks">Full Link</a> with an <a href="#InteractiveChangeIntegration">Interactive Change Integration</a> : Intent raises a synchronization issue on this link, that can be visualized and dealt with:<ul><li>through the Intent editor as any synchronization issue (EMF Compare dialog to visualize the issue and <em>"Mark as merged"</em> to accept the changes)</li><li>through the <a href="#DocumentationAttachmentsView">Documentation Attachments View</a></li></ul></li></ul><h3 id="Wikipagesaddition">Wiki pages addition</h3><p>Adding a new sub-document to an external document referenced through a <a href="Fulllinks">Full link</a> (typically, a new sub-page in a Wiki) is not considered as a minor document notification, as the content cannot be directly merged in the existing full link.</p><h4 id="Scenario07AddinganewsubpagetoareferencedWikipage">Scenario 07: Adding a new sub-page to a referenced Wiki page</h4><p><strong>As a</strong> documentation writer<br/><strong>I want to</strong> be notified when new sup-pages are created on a referenced Wiki page<br/><strong>So that</strong> I can decide whether to create a link for this page or not<br/><strong>Given</strong> an Intent document referencing (through <a href="Fulllinks)">Full links</a> a page on Intent Wiki (e.g. «Architectural overview»)<br/><strong>When</strong></p><ul><li>creating a new sub-page of «Architectural Overview» on the Wiki</li></ul><p><strong>Then</strong></p><ul><li>A synchronization issue indicating that a new page has been created should be raised</li><li>There are 2 ways of fixing this issue<ul><li>select the <em>"Reference this new page in Intent document"</em> quickfix: this will create a <a href="Fulllinks">Full link</a> on this page</li><li>select the <em>"Ignore this sub-page"</em> quickfix: this will create a <strong>@ref</strong> instruction with the sub-page URI, suffixed by <strong>@ignore</strong> to indicate that content should be ignored.</li></ul></li></ul><h3 id="Deletionofexternaldocuments">Deletion of external documents</h3><p>A deletion is handled as any synchronization issue. However, the <em>"Mark as merged"</em> quickfix will be replaced by <em>"Delete this reference"</em> and will delete the <strong>@ref</strong> instruction.</p><h3 id="Linkexternaldocumentwithtechnicalartifacts">Link external document with technical artifacts</h3><h4 id="Scenario08Linkingatechnicalartifactwithanexternaldocument">Scenario 08: Linking a technical artifact with an external document</h4><p><strong>As a</strong> documentation writer<br/><strong>I want to</strong> link an external document with a technical artifact (e.g. a java method)<br/><strong>So that</strong> I get synchronization issues on this external document when the artifact changes<br/><strong>Given</strong> an Intent document referencing (through <a href="Fulllinks)">Full links</a> a page on Intent Wiki (e.g. «Architectural overview») and a java file containing a method<br/><strong>When</strong></p><ul><li>I drop the technical artifact on the corresponding link in the Project explorer (remember that external documents are displayed in this view)</li></ul><p>OR</p><ul><li>I type the <strong>@ref "<MY_EXTERNAL_DOCUMENT_PATH>" {@ref "<MY_TECHNICAL_ARTIFACT_PATH>"}</strong> in the intent editor</li></ul><p>OR</p><ul><li>I click on the <em>"New attachment...</em>" button of the <a href="#DocumentationAttachmentsView">Documentation Attachments View</a> (this will open the <a href="#NewAttachmentDialog">New Attachment Dialog</a> and allow to select precisely which part of the document should be linked with the technical artifact)</li></ul><p><strong>Then</strong></p><ul><li>A new ExternalContentReference is added to the link’s map. If nothing specified, the MapEntry’s key will be the root of the external document, but if the <a href="#NewAttachmentDialog">New Attachment Dialog</a> was used we use the precise documentation element as key of this map entry.</li></ul><h4 id="DocumentationAttachmentsView">Documentation Attachments View</h4><p>This view reacts to any selection of an IntentStructuredElement (through the Intent Editor or the Project Explorer) or an external link (also displayed in the project explorer) by listing the associated technical artifacts, and all the documentation-releated synchronization issues (only in the case of a <a href="#Fulllinks">Full link</a> with <a href="#InteractiveChangeIntegration">Interactive Change integration</a> ).</p><p>When selecting some element (here an external link) in the project explorer, the view is updated (whether automatically if «link with selection» is enabled, or manually by clicking on "Refresh), and allows to:</p><ul><li><strong>Open</strong> the corresponding document (in an browser for a Wiki page, an Intent editor for a section...)</li><li><strong>Visualize</strong> and <strong>Mark as merged</strong> all synchronization issues for this link (none if it is an Intent structured element or a <a href="Reflinks">Ref link</a> )</li><li><strong>See</strong> attached technical artifacts (clicking on the <em>"Details..."</em> button will open the <a href="#TechnicalArtifactsDetailsDialog">Technical Artifact Details</a> dialog, and double-clicking on a technical artifact will open it with the appropriate editor – exactly as would have an hyperlink on the @ref instruction).</li><li><strong>Attach a new technical artifact</strong> (clicking on the <em>"New attachment..."</em> button will open the <a href="#NewAttachmentDialog">New Attachment Dialog</a> )</li></ul><p><img border="0" src="doc_attachments_01.png"/></p><p>Notice that this view has the same behavior for Intent structured elements:<br/><img border="0" src="doc_attachments_02.png"/></p><h4 id="NewAttachmentDialog">New Attachment Dialog</h4><p>This dialog allows to link a technical artifact with an Intent Structured Element or an external document (or, in case of a <a href="#Fulllinks">Full link</a> , a precise sub-part of an external document).</p><p><img border="0" src="new_attachment_dialog_01.png"/></p><h4 id="TechnicalArtifactsDetailsDialog">Technical Artifacts Details Dialog</h4><p>From the <a href="#DocumentationAttachmentsView">Documentation Attachments View</a> , when selecting an attached technical artifact and clicking of the <em>"Details</em>" button, the following dialog is opened:<br/><img border="0" src="technical_artifacts_details_01.png"/><br/>It allows to:</p><ul><li><strong>Open</strong> the corresponding artifact with the appropriate editor (e.g. Java editor for java method)</li><li><strong>Visualize</strong> and <strong>Mark as merged</strong> all synchronization issues related to this artifact</li></ul><h3 id="Livingwithchangesintechnicalartifacts">Living with changes in technical artifacts</h3><p>The Intent synchronization mechanism will work exactly as usual: when detecting changes on the referenced technical artifacts, it will create synchronization issue markers on the <strong>@ref instructions</strong> contained in the link map. We will add an additional <em>"Open Corresponding document"</em> quickfix that will open the target external document (and in case of a full link select the proper location).</p><p>But this standard mechanism can become hard to use when dealing with several documents and several synchronization issues.</p><p>That is why we provided 2 additional ways of seeing and fixing these synchronization issues:</p><ul><li>When the attached document is in the workspace, we will <strong>create synchronization markers</strong> on this doc file</li><li>Using the <a href="#DocumentationAttachmentsView">Documentation Attachments view</a></li></ul><h3 id="Intentdocumentationexport">Intent documentation export</h3><p>An Intent document containing references to external documents will be exported as a standard Intent document, with the following rules:</p><ul><li>for external documents referenced through a <a href="Fulllinks">Full link</a> , the whole content of the document will be exported</li><li>for external documents referenced through a <a href="#Reflinks">Ref link</a> , we will define a boolean preference <em>"Ignore ref links during export"</em>:<ul><li>if true, nothing will be exported (we will not create a link toward the external document)</li><li>if false, we will export a link toward the external document</li></ul></li></ul></body></html> |