VideosCollaborative Authoring Using Subversion

Overview

This demonstration shows how members of a documentation team can collaborate using oXygen and Syncro SVN Client.

Transcript

00:00:09This demonstration shows how members of a documentation team collaborate
00:00:13 using oxygen XML
00:00:15and Syncro SVN Client.
00:00:18For simplicity sake our authoring team is composed of three members
00:00:21but the principle can be scaled up for a larger team.
00:00:25 The setup is composed of an SVN repository
00:00:28where the documentation project is stored and oXygen XML Author
00:00:32or oXygen XML Editor for editing the documentation content
00:00:37and Syncro SVN Client, a Subversion client application
00:00:41capable of managing a collaborative work style.
00:00:45The three authors working on the project are:
00:00:49John, the subject matter expert who will input raw documentation,
00:00:53Tom, the technical writer who refines the documentation content
00:00:57and puts everything together to comply with the DITA style guide
00:01:01and Emily who does the proofreading
00:01:05and final editing of the documentation.
00:01:10Tom is in charge of writing
00:01:12the documentation for a mobile phone line of products. He already wrote some of the content
00:01:16and organize the documentation in an oXygen XML project which contains
00:01:21DITA topics, tasks and concepts
00:01:24organized in a DITA map, images referred in the documentation
00:01:28and settings like format and indent sizes
00:01:32custom transformations scenarios, custom profiling condition attributes and sets
00:01:37oXygen automatically saves all these settings
00:01:41 at project level to allow sharing them with the other members
00:01:44of the documentation team.The DITA topics are organized in a DITA map
00:01:49and covers the basic description and usage of the mobile phone models.
00:01:53Now Tom will share the documentation project
00:01:56with his team .He starts Syncro SVN Client from the Tools menu
00:02:04He configures a repository location to a known server.
00:02:06
00:02:13Then he browses the repository to the folder where he wants to start the
00:02:16project
00:02:17Then he shares the project.
00:02:35After adding the project to the remote
00:02:36repository Syncro SVN Client automatically switches to the working copy view.
00:02:41Now Tom copies the repository URL
00:02:44and shares it with the other members of the team.
00:02:59Now John is invited to contribute to the Mobile phone documentation project.
00:03:03He uses the URL information to configure the repository location
00:03:08in his copy of Syncro SVN client.Then he browses the remote repository
00:03:14and checks out locally the documentation project.
00:03:37Now he opens the oXygen project file to allow
00:03:40oXygen to load all the documentation projects resources
00:03:43and associated settings.
00:03:46
00:03:50found in today's mobile phones. He just creates a new topic file from the oXygen
00:03:56New file wizard
00:03:57changes the topics name and then inputs raw technical information
00:04:01about two phone cameras.
00:04:05He's not a DITA expert, hence he is not focused on creating a topic that conforms
00:04:10 with the DITA styleguide.
00:04:11This is Tom's job who will further refine the topic content later on.
00:04:16Then he saves the topic and switches to Syncro SVN Client to
00:04:20commit the newly created topic.
00:04:29In the working copy view, under the Modify tab,
00:04:32the newly created file appears as unversioned
00:04:35so John invokes the Commit action from the file's contextual menu.
00:04:39He inputs a message and then hits the Commit button.
00:04:50Back to Tom,he just checks the documentation repository
00:04:53 to see if there are any updates. Syncro SVN Client
00:04:58reports that John added a new file today.
00:05:02Tom updates his working copy with a new file and then opens it
00:05:05in oXygen XML.
00:05:13Tom uses the information John provided
00:05:15and starts refining the topic.
00:05:18then inserts a table and fills it with the camera specifications
00:05:32then adds images with the two mobile phone models.
00:05:41Now he decides to profile the content.
00:05:43One of the columns holds information about the X 1000 model,
00:05:47while the second one holds information about the
00:05:50X2000 model.
00:06:00In the same way, Tom profiles
00:06:02 the two images.
00:06:12Then he performs a quick check to see how the profiled documentation
00:06:15looks like when he uses a specific profiling conditions set.
00:06:26Now he realizes that the specificaition table
00:06:28lacks information about the camera frame per second rating.
00:06:31He inserts a comment in the topic asking John
00:06:35to add the required information.
00:06:40Then he saves the topic and adds it in the DITA map.
00:06:49Now he saves the DITA map too and switches to Syncro SVN Client.
00:07:00He synchronizes his working copy
00:07:01with a remote repository.
00:07:05Syncro SVN Client reports that two of the resources are in a conflict state
00:07:09because in the meantime, the other member of his team,
00:07:12Emily committed her work to the repository.
00:07:16Both Emily and Tom modified 2 of the files in the same time,
00:07:20hence the conflictual state reported by Syncro SVN Client.
00:07:24Now Tom needs to solve the conflict before being able to
00:07:28commit his modifications.
00:07:30Tom starts with the first file which is
00:07:33specs.dita.
00:07:37After double clicking it, the 2 versions of the file are opened side by side in the Diff mode.
00:07:40The first difference is a true conflict.
00:07:45Emily added a more meaningful title and Tom accepts
00:07:48this change.
00:07:52You can see Tom's
00:07:53changes highlighted in light grey.
00:08:00Tom accepts the incoming
00:08:02change from the bottom of the file
00:08:03and he saves his revision of the file.
00:08:07Now that he incorporated Emily's modification, he marks the file
00:08:11as merged. Note that SVN Client
00:08:14has now changed the status of the resource as outgoing.
00:08:21Now he takes care of the second file reported as conflict.
00:08:21In the Diff view
00:08:25he sees that this is actually a false conflicting state.
00:08:29Both Tom and Emily inserted topics in the DITA map structure
00:08:34but they do not conflict with each other.
00:08:38Tom updates the file and Syncro SVN Client merges
00:08:41the two revisions.
00:08:47Now we can see that Diff view
00:08:48reports only outgoing changes in the DITA map.
00:08:56
00:08:56Tom updates his working copy with the Emily's new topic
00:08:59and commits his changes.
00:09:11Back to John...
00:09:16He updates his working copy
00:09:18and switches to oXygen.
00:09:34He sees Tom's comment and inserts the required information.
00:09:38
00:09:42Then, he removes the comment
00:09:44and saves the file.
00:09:54Then he switches to Syncro SVN Client
00:09:56and commits his modifications.
00:10:15Now Tom synchronizes his working copy
00:10:23and starts reviewing the topic.
00:10:24
00:10:27One by one he accepts the changes
00:10:29made by his coworkers.
00:10:42He's happy with the content
00:10:44and he decides the commit the final form of the topic.
00:10:59Now Emily, our proofreader,
00:11:00has already updated her working copy and reviewed the
00:11:04content of the project.
00:11:05She switches to the History tab to see how the project evolved over time.
00:11:09Here, the following information is available:
00:11:12revision date, the number of files modified at each revision
00:11:17author name and a short commit message.
00:11:20She's happy with the current form of the project
00:11:23and she decides to mark or tag
00:11:26this release version of the documentation. She uses the Branch/Tag action from the
00:11:31contextual menu.
00:11:33She browses the repositary structure to set the tags destination folder,
00:11:38 then she chooses a meaningful name
00:11:41and commit message of this documentation snapshot.
00:11:52Now the tag is stored in the repository. This was the last step
00:11:57of a documentation workflow using oXygen XML and Syncro SVN Client.
00:12:00We've seen how members of a documentation team
00:12:04used oXygen XML to edit,profile and review documentation
00:12:09and Syncro SVN Client to manage all changes made
00:12:13to the project.
00:12:15And this concludes our demonstration. Thanks for watching.