TaskD Overview
D. Documentation
State: In progress
Time used: 0 md.
Description
The DOMS project is expected to produce documentation in the below categories:
- Documentation for developer use, such as coding guidelines, guidelines for how to use the development environment.
- Documentation for the system managers that will be managing and operating the DOMS in the production environment.
- Documentation/Guidelines for installation of the DOMS, any software components that it depends on, and instructions for a proper configuration of the run-time environment.
For each of these documentation categories there must also be produced guidelines for layout and contents to ensure that documents produced by different authors are uniform.
Sub tasks
Parent task
Progress history
| Iteration | Time used | Status | Notes | |
| ActionFedoraXACML Evaluation | 10 | 3md | Finished | Evaluate if the Fedora XACML authorization system is sufficient for DOMS |
| ActionSystemDocumentation | 13 | 4md | In progress | Depends on "Action WSDL2 Java" |
2008-06-03
Updated this group with results of Doms Day Discussions. Each leaf-task now contains a list of expected documents.
2008-04-21
Made a round-up of what parts of this task have been made so far and by whom. See details here.
D.1. Make Documentation Guidelines
State: Not started
Time used: 0 md.
Description
The goal of this task is to write documentation guidelines and documentation templates for the documentation in the DOMS project. The guidelines should standardise the DOMS documentation (to some extent) and ease documentation writing.
Sub tasks
![/!\](/domswiki/moin_static1911/modern/img/alert.png "/!\")
D.1.3. Guidelines for guide for introducing new collections / material into DOMS. - D.1.4. Guidelines for system maintenance documentation.
- D.1.5. Guidelines for user documentation for librarians.
- D.1.6. Guidelines for user documentation for library users.
= Deprecated sub-task (replaced by D.1.7).
Parent task
Progress history
| Iteration | Time used | Status | Notes |
D.1.1. Guidelines for Design Documentation
State: Finished
Time used: ??? + review 3/2 md.
Description
Write guidelines for analysis and design documents. Decide if the documentation should be written in the wiki. Decide on a program for drawing diagrams.
Documentation
Parent task
Progress history
| Iteration | Time used | Status | Notes |
2007-10-12
Corrections done. We (kfc and bam) should meet to review corrections.
2007-10-09
- Reviewed by kfc and bam. There are a number of trivial correction, and we need guidelines for the project management pages. Follow-up: bam.
2007-09-13
We have decided to try to write all documentation in the wiki. Guidelines for analysis and design documents are written as templates: AnalysisDocumentationTemplate and DesignDocumentationTemplate, and they are also summarised in the DOMS Documentation and Wiki Site Guidelines.
We have decided on the Dia program for drawing structured diagrams as our primary diagram editor, and this recommendation is also included on the DOMS Documentation and Wiki Site Guidelines page. See DOMS Documentation and Wiki Site Guidelines for the full guidelines.
Analysis of Guidelines for Design Documentation
Prerequisites and Assumptions
The estimation of this task is based on these notes, which also should be taken into consideration when implementing the task:
BAM: No comments.
TE: Fremlæggelse tager tid
TSH: No comments.
MKE: No comments.
KFC: Nogen planlægger, plenum diskussion, indretning.
D.1.2. Guidelines for Javadoc
State: Finished
Time used: 0 md.
Description
Write guidelines for how and when the developers should write Javadoc in the code.
Documentation
Parent task
Progress history
| Iteration | Time used | Status | Notes |
2007-09-13
The page Javadoc Guidelines has been generated and is considered finished in the scope of this task.
The CodeStyle page also provides a setup file for IntelliJ, which accommodates formatting of javadoc.
Analysis of Guidelines for Javadoc
Prerequisites and Assumptions
The estimation of this task is based on these notes, which also should be taken into consideration when implementing the task:
BAM: No comments.
TE: Fremlæggelse tager tid + præcisering
TSH: No comments.
MKE: Versioning of classes
KFC: Præcisere specifikke ting
D.1.7. Guidelines for External Documentation
State: Not started
Time used: 0 md.
Description
We need to create guidelines for the layout, structure and so on for documentation written for people outside the DOMS project, such as end-users and system maintenance people.
Documentation
Parent task
Progress history
| Iteration | Time used | Status | Notes |
Analysis of Guidelines for External Documentation
Prerequisites and Assumptions
The estimation of this task is based on these notes, which also should be taken into consideration when implementing the task:
BAM: Doc. template (tabeller)
TE: Template med noter
TSH: Dok. template indeholdende obl. overskrifter + tabel-layout etc.
MKE: Guidelines for usergroups: maint., libr., users
KFC: Dokumentskabelon + beskriv målgruppe; Tabeller
D.1.8. Wiki Guidelines
State: Finished
Time used: 0 md.
Description
Set up a wiki for the DOMS project. Create the necessary templates and guidelines for usage of the wiki.
Parent task
Progress history
| Iteration | Time used | Status | Notes |
2007-10-16
This task was created on basis of the now deprecated task F.3.
2007-09-13
The final product of this task can be found here: DOMS Documentation and Wiki Site Guidelines All the pages comprising the basic structure of the wiki contains comments with guidelines for creation of sub-pages and each template contains the relevant guidelines for its own usage.
D.2. Write Developer Guidelines
State: In progress
Time used: 0 md.
Description
Write guidelines for the developers on how to handle exceptions, runtime errors, logging and so on.
Sub tasks
Parent task
Progress history
| Iteration | Time used | Status | Notes |
D.2.1. Exceptions
State: Finished
Time used: 0 md.
Description
Write guidelines for where, when and how to throw and catch Exceptions in the code.
Parent task
Progress history
2007-09-13
The page ExceptionGuidelines has been generated and is considered finished in the scope of this task.
Summary: Exceptions are seen as either contingencies or faults. The concept of fault handlers is introduced.
D.2.2. Logging
State: Finished
Time used: 0 md.
Description
Write guidelines for logging.
Parent task
Progress history
2007-09-13
The page LoggingGuidelines has been generated and is considered finished in the scope of this task.
D.2.3. Handling of constants and properties/settings
State: Finished
Time used: 0 md.
Description
Write guidelines for how the developers should handle and share common constants and properties in the DOMS.
Parent task
Progress history
2007-09-13
The page PropertyGuidelines has been generated and is considered finished in the scope of this task.
Summary: Properties can be nested and defaults are stated in a separate property file, typically embedded in a jar together with the corresponding classes.
D.2.4. Coding Guidelines
State: Finished
Time used: 0 md.
Description
Write guide lines for how the developers must format the code they write in order to obtain a consistent formatting of the DOMS code base. That is, we want to ensure that all developers indent their code in the same way, format their comments in the same way and so on.
Parent task
Progress history
2007-09-13
The coding guidelines can now be found on the CodeStyle page under Guidelines.
D.2.5. QA Guidelines
State: In progess, only missing review
Time used: 2 md. Note: Time spent before iteration 3 not measured.
Description
Write a guideline for how to perform quality assurance of the code produced in the DOMS project. This guideline must specify the measures that should be used in the DOMS project to ensure a good code quality and how to use them. E.g. specify how to perform peer code review and so on.
Parent task
Progress history
2007-09-20
The QA guidelines can now be found on the QA Guidelines page under Guidelines.
2007-09-24
A tool for generating a DocBook: of wikipages for use in QA has been written.
D.2.6. Internationalisation Guidelines
State: Finished
Time used: 0 md.
Description
Write guidelines for how the developers should make the code support internationalisation to ensure that the internationalisation will be implemented in a homogeneous way through out the DOMS code base.
Parent task
Progress history
2007-09-20
The guidelines for internationalisation can now be found on the i18n page under Guidelines.
D.2.7. Tool Guidelines
State: Finished
Time used: 0 md.
Description
Write guidelines for the developers about how to use and configure the tools used in the development of the DOMS. The document should give the developers an overview over what tools they are expected to use and guidelines for non-trivial usage, configuration and installation procedures.
Parent task
Progress history
2007-09-20
The tools guidelines can now be found on the Tools page under Guidelines. However, some of the sub pages are still unfinished.
D.3. Identify workflows requiring documentation, and generate it
State: Not started
Time used: 0 md.
Description
Identify any needs for documentation for external users and write it using the documentation guidelines. The needs for documentation may be identified by examining work flows, use cases, user roles and so on.
Sub tasks
D.3.1. Guide for introducing new collections / material into DOMS
- D.3.4. User documentation for library users
= Assumed obsolete, as the end users never will see the DOMS but only Summa.
Parent task
Progress History
| Iteration | Time used | Status | Notes |
2008-06-03
Updated sub tasks with lists of documents
D.3.1. Guide for Introducing New Collections / Material Into DOMS
State: Not started
Time used: 0 md.
Description
Write documentation on how to introduce new collections and material into the DOMS. This task calls for two documents; one describing what information is needed such as meta data for the new material, and one describing how to actually add the new material to the DOMS. The first document will be aimed at external users who need to store something new in the DOMS and the latter is aimed at the DOMS team / future DOMS administrators who actually are going to store the digital objects.
Sub tasks
Documentation
Parent task
Progress history
2008-06-03
Updated sub tasks with lists of documents
D.3.1.1. Write Guidelines Aimed At External Users
State: Not started
Time used: 0 md.
Description
Write documentation for external users on what information they must collect about new material or new collections in order to be able to store them in the DOMS.
Documents that need to be present before this task is complete:
- Guide for data submitters
Parent task
Progress history
2008-06-03
Updated task with lists of documents
D.3.1.2. Write Guidelines Aimed At Internal Users
State: Not started
Time used: 0 md.
Description
Write guidelines aimed at internal users on how to introduce new material / collections into the DOMS. Any internal user, that is, a DOMS team member or trained DOMS administrator must be able to add new material to the DOMS by following this documentation, provided that the external users have collected the necessary information about the material.
Documents that need to be present before this task is done.
- Guide for data owners, and data migrators
Parent task
Progress history
2008-06-03
Updated task with lists of documents
Analysis of Guide for Introducing New Collections / Material Into DOMS
When addressing this task, we should consult the following TDR requirements:
- Collection specific requirements we should consider to some degree in DOMS B1.3, B1.4, B1.6, B2.3, C2.1, R72
See TaskC.1AnalysisDocumentDetails#CollSpec
Prerequisites and Assumptions
The estimation of this task is based on these notes, which also should be taken into consideration when implementing the task:
BAM: ekstern + intern ?
TE: Skal bruges af rigtige mennesker
TSH: No comments.
MKE: Differentiate internal and external doc.
KFC: Eksternet henvendt dokumentation + internt henvendt dokumentation
D.3.2. System Maintenance Documentation
State: Not started
Time used: 0 md.
Description
Write documentation describing how to install the DOMS and how to maintain the installed system.
The goal is to write a document that enables any DOMS team member to install a full DOMS system and enables the system maintenance people to keep it running. That is, the document must contain a thorough installation guide and describe the DOMS software components and any components that it depends on, on a system level. Thus, enabling the maintenance people to supervise the system, checking its state and take proper action if the system shows any sign on irregularities.
Documents that need to be present before this task can be considered done:
- System maintenance documentation
- Application maintenance documentation
Documentation
Parent task
Progress history
2008-06-03
Updated task with lists of documents, including specification of System maintenance and Application maintenance as separate entities.
Analysis of System Maintenance Documentation
Prerequisites and Assumptions
The estimation of this task is based on these notes, which also should be taken into consideration when implementing the task:
BAM: både til drift og os selv
TE: Install, deploy, systems, detaljer, også til os selv
TSH: Quick Rescue Guide. Detalj oversigt over alle hjul og trisser som udgør systemet.
MKE: Extensive step-by-step for maint. AU components. Developer oriented.
KFC: Detaljeret deploy-dokumentation, system-dokumentation, "quick-help"
D.3.3. User Documentation for Librarians
State: Not started
Time used: 0 md.
Description
This documentation is expected to be delivered by Mjølner.
Documents that need to be present before this task can be considered done:
- UI End User documentation
Documentation
Parent task
Progress history
2008-06-03
Rewrote task. Mjølner is now expected to deliver this. Updated task with lists of documents
Analysis of User Documentation for Librarians
Prerequisites and Assumptions
The estimation of this task is based on these notes, which also should be taken into consideration when implementing the task:
BAM: Svær! Antaget undervisning og ...
TE: Andre laver arbejdet efter undervisning
TSH: Undervisning + dialog m. bibliotekar der skal skrive manual.
MKE: Guide to E1, and B (Summa) Undervisning + bruger=bib skriver manual
KFC: Undervisning+dialog med bibliotekat som skriver manual
D.4. Create Overall System Documentation
State: Not started
Time used: 0 md.
Description
Write high level documentation describing how the DOMS system works. The goal of the documentation is to illustrate the high-level architecture and give non-technical people an overview over the capabilities of the DOMS system as well as an overview over the TDR requirements which are supported and which are not. That is, the documentation is supposed to be more like a "product specification" rather than a developers or end user documentation.
Sub tasks
Documentation
Parent task
Progress history
| Iteration | Time used | Status | Notes |
2008-06-03
Updated subtasks with lists of documents. Added task for Data Model Documentation
2007-10-05
Created this task from TDR requirements. See subtasks for details.
D.4.1. Write White Paper
State: Not started
Time used: 0 md.
Description
We will need a white paper describing the high level system architecture and the background for the design decisions made, such as repository principles, prerequisites and the objectives of implementing the DOMS. E.g. the expected delivery of preservation services from the PLANETS project is a prerequisite of this project which is supposed to contribute to achieving the objective of making the DOMS a trusted digital repository.
Documents that need to be present before this task can be considered done:
- White Paper
Documentation
Parent task
Progress history
2008-06-03
Updated task with lists of documents
Analysis of Write White Paper
While solving this task, we must address the following TDR requirements:
- Document and communicate repository principles for TDR fulfilling requirements from A1.1, A1.2, A3.4, D1.8, R12, R73
- Need documentation of software dependencies: D2.2
- Requirements to IT maintenance department (Note: these are also addressed in Task A.3): D1.1, D1.2, D1.5, D1.6, D1.7, D1.10, D2.1, D3.1, R30-47, R60, R74-76
See TaskC.1AnalysisDocumentDetails#DocumentRepositoryPrinciples
See TaskC.1AnalysisDocumentDetails#DocumentSoftwareDependencies
See TaskC.1AnalysisDocumentDetails#ITMaintenance
Prerequisites and Assumptions
Risks and Potential Problems
D.4.2. Document TDR requirements
State: Not started
Time used: 0 md.
Description
Document the trusted digital repository (TDR) requirements implemented by the DOMS system and describe any requirements which must be implemented by other parties/systems in order to make the DOMS a TDR.
Documents that need to be present before this task can be considered done:
- Documentation of TDR requirements met, and external requirements before we can be a TDR
Documentation
Parent task
Progress history
2008-06-03
Updated task with lists of documents
2007-10-05
Created task based on identification of TDRs
Analysis of Document fulfilled TDR requirements
When addressing this documentation, we should consult the following TDR requirements:
- Communicate requirements out of scope for DOMS but relevant for SB: A2.*, A3.3, A4.*, A5.*, B1.2, B3.11, C1.*, C2.1, C3.1, C4.*, D1.6, D1.8, D1.9, D2.3, D3.1, D3.3, D3.4, D3.5, D3.6, R01-10, R13-14, R16-47, R57-58, R72, R74-76, R78
- Organizational procedures required around deployment A3.*, D1.8, D.2.2
See TaskC.1AnalysisDocumentDetails#CommunicateReqsOutOfScope
See TaskC.1AnalysisDocumentDetails#OrgProcDeployment
Prerequisites and Assumptions
Risks and Potential Problems
D.4.3 Document Data Model Language
State: Not started
Time used: 0 md.
Description
Document the data model used in DOMS. This includes a system-readable language.
Documents that need to be present before this task can be considered done:
- Data Model language
Sub tasks
Documentation
Parent task
Progress history
2008-06-03
Created task after Doms Day Discussion
D.5. Create Preservation Strategy Documentation
State: Not started
Time used: 0 md.
Description
We need to describe our preservation strategy, including preservation characterisation/action by integrating with Planets, and active logical integrity checking. That is, state our strategy for how we are going to ensure that all the objects stored in the DOMS will be available in valid formats in the future. This comprises a description of how we will detect when the format of any stored object is about to become obsolete, how we will determine what alternative format that would be the appropriate to use, and how we will ensure that the object is properly converted to this format.
Documents that need to be present before this task can be considered done:
- Preservation Strategy Documentation
Documentation
Parent task
Progress history
| Iteration | Time used | Status | Notes |
2008-06-03
Updated task with list of documents
2007-10-05
Created task based on TDR analysis
Analysis of Create preservation strategy documentation
When addressing this task, we must address the following TDR requirements:
- Must have preservation strategy for certain classes of digital material B1.1, B3.1, R65, R66
- It must be possible to document how we ensure integrity A3.6
- Need preservation strategy (Planets): B3.1, B3.2, B3.5, B3.9, B3.10, R65-67
See TaskC.1AnalysisDocumentDetails#FormatPreservationStrategy
See TaskC.1AnalysisDocumentDetails#Integrity
See TaskC.1AnalysisDocumentDetails#PreservationStrategy
Prerequisites and Assumptions
Risks and Potential Problems
Stakeholders
Stakeholder |
Knowledge |
Usability expert. |
|
Expert on mixing margaritas |
|
The guy with the money who actually may know what he wants. |
Ressources
Task D.6 Create API/Interface documentation
State: Not started
Time used: 0 md.
Description
Document APIs/interfaces for at least the following:
- Ingest
- Repository API (will probably include references to Bitfinder, OAI-PMH, Datamodel, and Fedora documentation)
- Validation Tool API
Sub tasks
Documentation
Parent task
Progress history
| Iteration | Time used | Status | Notes | |
| ActionSystemDocumentation | 13 | 4md | In progress | Depends on "Action WSDL2 Java" |
2008-06-03
Updated task with list of documents
Task D.7 Design Documentation
State: Not started
Time used: 0 md.
Description
All parts of the system need to have design documentation. Documentation of special interest includes at least:
- Fedora setup and use
Summa integration (DigitalObjectBundle, OAI, PlayBack disseminators)
- UI developer documentation
- Validation tool documentation
Sub tasks
Documentation
Parent task
Progress history
| Time used | Status | Notes | |
| ActionFedoraXACML Evaluation | 3md | Finished | Evaluate if the Fedora XACML authorization system is sufficient for DOMS |
2008-06-03
Updated task with list of documents
Round-up of Task D
This page describes the current state of task D as of 21th April 2008. That is, a status of all work performed on this task and its sub-tasks so far, and a overview over the developers whom perforned the work.
Sub-tasks addressed so far:
Task |
State |
Developer(s) |
|
Finished |
BAM, TE, MKE, KFC, TSH |
||
Finished |
TE, MKE |
||
Deprecated |
TSH |
||
Deprecated |
TSH |
||
Deprecated |
TSH |
||
Deprecated |
TSH |
||
Not started |
N/A |
||
Finished |
BAM, TSH, MKE |
||
Finished |
BAM, TE, MKE, KFC, TSH |
||
Finished |
BAM, TE, MKE, KFC, TSH |
||
Finished |
BAM, TE, MKE, KFC, TSH |
||
Finished |
BAM, TE, MKE, KFC, TSH |
||
In Progress |
BAM, TE, MKE, KFC, TSH |
TSH: Burde QA guidelines anbefale en given hyppighed af releasetests mv.? |
|
Finished |
BAM, TE, MKE, KFC, TSH |
||
Finished |
BAM, TE, MKE, KFC, TSH |
||
Not started |
N/A |
||
Not started |
JRG, TSH |
TSH:Denne task er ikke berørt mht. maxi-DOMS skal laves? |
|
Not started |
N/A |
||
Deprecated |
TSH |