Received: from [192.168.0.1] (root@raven.ravenbrook.com [193.82.131.18]) by raven.ravenbrook.com (8.9.3/8.9.3) with ESMTP id RAA12138 for ; Sat, 7 Oct 2000 17:56:14 +0100 (BST) Mime-Version: 1.0 X-Sender: rb@pop3-ravenbrook Message-Id: Date: Sat, 7 Oct 2000 12:25:22 +0100 To: Perforce Defect Tracking Integration Project staff From: Richard Brooksby Subject: Notes from documentation meeting, 2000-10-07 Content-Type: text/plain; charset="us-ascii" ; format="flowed" RB, GDR, and LMB met at PP to work on the SAG and the UG. We spent 1 hour expanding the SAG and a somewhat similar amount of time deciding which use cases and requirements to document first. 1. Marking DT-specific text We will use
for block-level DT-specific parts (e.g. sections), and for phrase-level DT-specific text (e.g. sentences). Don't worry about being too precise. The main thing is to mark the text so that we can process it later. 2. Worked example It's probably a good idea to have a worked example throughout the SAG and probably the UG as well. For TeamTrack we can use the TeamTrack sample database, which has an example workflow. The replicator will be pre-configured for this anyway. The main problem is that the example will be different for each DT, so it'd need to be isolated to the DT-specific text. GDR says that the configuration is mostly going to be DT-specific anyway, so this might not be a problem. 3. Default configuration The integration will come with a configuration for the TeamTrack sample database, which comes with TeamTrack ("ttracksample.mdb" in the "Program Files\TeamShare\TeamTrack\Database" directory). That'll be the example. (We could provide a example repository to go with it, or a script for creating one. We're not sure whether we want to document this in the SAG.) 4. Training and documentation We're going to provide the UG which will be "how to" documentation for the use cases and requirements. But this section will recommend getting the users together and telling them about the integration and how to use it, in overview. LMB suggests we provide a presentation outline. GDR suggests that we cover some key stuff that users should or shouldn't do (e.g. "don't edit the P4DTI-*" fields in jobs"). RB will write this presentation, as it's needed for the alpha programme anyway. We need to cover how to use it, and what to do when it goes wrong, for example, when a conflict happens, or when they come across a conflicting issue. This presentation material will also be useful for the user guide. 5. Going live When the admin is configuring and testing, he doesn't want to use the real database. We should explain this earlier on. And we'll need to explain how to make the integration work on the real data smoothly. We can provide a plan, and contingency plans for if things go wrong. For example, recommend coming in early in the morning or over a weekend. We can estimate how long it will take. Configuration should've taken place on a duplicate of their real data. This might not be feasible if the real data is a 10Gb Perforce repository and a 100Gb corporate Oracle database. We'll need to think about that one. They'll need to re-run the testing on the live system as well. (The earlier testing was to make sure the configuration worked, this is to make sure the live system is working.) They should then watch the system working for a while. We should list things to look out for. 6. Message IDs All of the messages that come out of the system should have message IDs so that we can map them into documentation, either locally, or centrally, and so that support can identify each message. 7. Manager's guide Maybe there needs to be a manager's guide to cover installing the integration in the _organization_. These are the headings I wrote on the topic in my earlier message. Organization Guide What you will need Someone to install the product Someone to configure the product Configuration decisions Someone to administrate the product Resolving conflicts Someone to maintain the product Training Also there's the policy decisions that need to be made. 8. User guide by role We must make it clear that the headings in the user guide are _roles_ not people. GDR suggests making the headings "development tasks" rather than "developer tasks" to make this clearer. 9. Use case priorities [GDR 2000-05-03] "Requirements and Use Cases for Perforce/Defect Tracking Integration"; Gareth Rees; Ravenbrook Limited; 2000-05-03. Here are the cases to document, in order. 6.19 View list of assigned tasks 6.5 Associate changelists with tasks 6.6 Submit a changelist 6.8 Simultaneously submit changes and complete task 6.7 Complete a task 6.1 Create task 6.16 Find changes resulting from an issue 6.13 Find issues associated with changelist 6.2 Associate revisions of documents with task 6.11 Find issues associated with documents 6.14 Find revisions of documents associated with an issue 6.3 Check out copies of revisions of documents associated with task 6.12 Find issues associated with version or release 6.15 Find version or release associated with an issue 6.4 Make a branch to work on a task 6.9 Find tasks being worked on in workspace 6.10 Find workspace in which task is being worked on Not planned to be supported by P4DTI 6.17 Attempt to read document without permission 6.18 Attempt to edit document without permission 10. Requirements priorities Requirements 1 to 5 are a good source for "overview" material. Requirements 20 to 29 are about extending and developing the system. We'll probably want an "extender's guide" which we'll refer to from the other documents. All the documents should refer to each other in the introduction.