With a healthy approach to documentation, documents are produced in a cycle. Beginning in the development of a new product and ending with the consumer, many types of documentation are produced, revised, and reworked.

A proper documentation strategy allows an individual to pull from the work of those around them while granting the flexibility for new document creation and evolution. This same strategy should allow for easy updating of collaborative documents and simultaneously reduce redundancy.

Do you find yourself digging in an e-mail to reference an attachment sent weeks ago? Or you're forced to contact someone for the latest version of a document and wait for them to respond? Are you regularly interrupted by coworkers with questions because a reference repository doesn't exist?

What if all documents lived dynamically in the same place, and accessing them only required a log in? How much time would it save if websites could be created for your document's intended audience and updated simply, without having to update each individual site?

This strategy intends to address the needs of the SPS Agasti development team and the future needs of the School of Professional Studies Office of Information Technology (SPS OIT). It will then lay the groundwork for long-term document management solutions for SPS Agasti, SPS OIT, and other possible future expansions.

All documents published by the School of Professional Studies Office of Information Technology will contain a licensing statement. This includes published works, PDFs, websites, and other completed documentation. A Daisy Collection titled “Licenses” will be available to most roles for a standard library of licensing statements.

The primary software used for the SPS Agasti project's documentation is the Daisy CMS; however, other programs will be necessary to accommodate the range of the documents produced. Though it's not a comprehensive list, Open Office, Redmine's wiki feature, blogs, and Doxygen will be utilized.

The Daisy Content Management System is primarily used for “completed thought” documentation. These are documents of all types that have moved beyond the scratch-paper and brainstorming stages. Anything intended to be shared with other members of the team, for collaboration or policy documentation, will be included in this pool.

The documents included in Daisy CMS will be sorted using the collections feature; which will also manage the access to individual documents and document sets. Though the entirety of Daisy's repository will not be moderated, it's intent will be to contain near-completion and publication-ready documentation; both for archival and easy reference.

As the Daisy CMS will be a more formally structured repository, the team will want a place for brain-storming and quick documentation. Redmine's wiki feature has been enabled for all SPS IT projects, including Agasti, and is for brainstorming, quick notes, and as a writing resource to allow ideas to fully develop.

These areas will have low moderation to allow the free-flow of thought. When the ideas stored here move to cohesion and implementation they are transferred to Daisy by the content creator in collaboration with an SPS Content Manager.

As it is a familiar set of tools, the Open Office suite is used regularly by the SPS Agasti team for creating text-based documents. To ensure easy conversion up-stream to Daisy, use of document formatting and styles is essential. Document formatting in Open Office Writer

All documents created in Open Office Writer shall:

• Use the Styles and Formatting menus for all content to ensure proper transfer.
• Contain a footer with:
  • Author
  • Page Number
  • Total Pages
  • Date of creation
  • Date updated
• Contain a concise title at the top of page one that adequately describes the content within. (This will be used at the title when the document is transferred to Daisy). This title will be styled with “Heading 1”.

Doxygen is SPS Agasti's preferred engine for in-line documentation. Developers are responsible for maintaining their own in-line documents; however the document stores produced from this engine will likely be exported to Daisy for later reference. In line syntax must comply with Doxygen's standards. In-line documentation is governed by the Technical Documentation Guidelines.

Below is a quick-reference guide for what software is used to develop and store different types of documents.

Different documents will be governed by different standards as follows:

Standard English documents written in plain language will be governed by the Plain Language Document Standards.

In-Line documentation produced during code development will be governed by the In-Line Document Standards.

Documents in the Daisy CMS are organized into Collections: documents grouped together with varying levels of access and control. Each collection has customizable access levels for viewing, editing, publishing, versioning, and book inclusion. A document can belong to as many or as few collections as the creator/editors feel it needs to; or none at all. Daisy Introduction

A collection of documents on the use of Daisy, including this document, how-to's, FAQs, and tips and tricks. All users will have access to this Collection, regardless of their other permissions.

This collection is used to house documentation generated by the SPS Agasti Developers. While some of these documents will remain only in this collection for reference; other documents will be made available for reference texts and end-users by being added to other collections.

Access is be available to “Agasti Dev”, “Agasti Management”, and “Agasti Admin” users.

This collection will house documentation intended for Agasti end users, such as how-tos, walk-throughs, and FAQs. There will be overlap with the Agasti Development collection.

Access is available to “Agasti Dev”, “Agasti Management”, and “Agasti Admin” and viewable to “OEM Management”, “OEM Users”, and “OEM Admin”.

Some documentation required by OEM is too technical for the general OEM user's training. To prevent confusion, this collection houses technical documentation, reference texts, db schema, and other similar information.

Access is available to “Agasti Dev”, “Agasti Management”, and “Agasti Admin” as well as “OEM Management”, and “OEM Admin”

Some information required by OEM is not be appropriate for general access. Documents of this nature can be found in the OEM Management collection.

Access is available to “Agasti Management”, and “OEM Management”.

This collection is used for internal SPS IT infrastructure documentation; such as server locations, names, and infrastructure planning. Access will be limited to internal SPS IT Administrators.

A large collection of reference texts, policy, and training materials for SPS IT.

Access is available to “SPS IT Admin”, “SPS Content Manager”, “Agasti Dev”, and “Agasti Management”.

This collection will be a training repository for SPS IT.

Access is available to “SPS IT User”, “SPS IT Admin”, “SPS IT Content Manager”, “Agasti Dev”, and “Agasti Management”.

A collection for SPS IT policy, workflow, and reference. Editable by “SPS Admin” and viewable by “SPS Instructor”, “Agasti Dev”, “Agasti Management”, and “Agasti Admin” users.

A collection of standard licensing language for use in published SPS OIT documentation.

Write access is available to “Agasti Dev”, “Agasti Management”, “SPS IT Admin”, “SPS Content Manager”.

Read access is available to all other roles.

While the interface requires a steep learning curve, Daisy CMS' ACL is highly customizable and flexible. The following sketches the permissions structure for Daisy, their expected document requirements, and collection access.

Roles required for maintaining Daisy.

The default role for new accounts. Access will be limited to the Daisy Introduction Collection until another role has been assigned.

The Daisy CMS is managed by an administration set that has access to all documentation in the repository, as well as collection management, automated workflow creation, book publishing, and all other features within Daisy. This role is highly priviledged, requires technical acumen and a complete understanding of Daisy's structure. As such, access is limited to as few responsible individuals as is reasonable to maintain the repository.

For the purposes of this document, there are two sides to the SPS Agasti project: OEM and the SPS Agasti team.

OEM Management are high-level decision makers and shareholders who will have access to all reference materials and documentation.

Write Access: OEM Administration, OEM Management

Read Access: SPS Agasti Training, Daisy Introduction

OEM Users are internal OEM employees who are familiar with Agasti, yet are not administrators. There may include trainers, program managers, and other city employees interacting with Agasti and requiring access to reference materials.

Read Access: SPS Agasti Training, Daisy Introduction

OEM Admins are OEM employees with an intimate relationship to Agasti who are maintaining the program instance. They require a higher level of access and knowledge without access to sensitive documentation.

Write Access: SPS Agasti Training, OEM Administration

Read Access: SPS Agasti Development, Daisy Introduction

The SPS Agasti Team consists mostly of Agasti Developers. They are the primary document creators for the development process and most other Agasti related documentation will be based on their work.

Write Access: SPS Agasti Development, SPS Agasti Training, OEM Administration, Daisy Introduction, SPS IT Reference, SPS IT Policy, SPS IT Training

Beyond the developers of the Agasti team are users involved in day-to-day workflow, policy, and decision making for the Agasti project. They require the access to implement higher level business decisions.

Write Access: SPS Agasti Training, SPS IT Infrastructure, OEM Administration, OEM Management, Daisy Introduction

It is likely that SPS OIT will eventually use Daisy for organization and document sharing. Below are the potential roles for that instance with the understanding that they would be revisited before implementation.

SPS IT system administrator.

Write Access: SPS IT Infrasturcutre, Daisy Introduction, PSS IT Reference, SPS IT Trianing

Read Access: SPS IT Policy

SPS Administrators and management.

General access to SPS policy documents, images, and other related information.

Different types of documents require different workflows; yet the majority can be classed into several categories for easy reference and control.

For the purposes of this document, the content creator is any person or group of persons that is involved in the creation of a document or set of documents. Throughout the development of the document and its information they are responsible for crafting and maintaining it in co-ordination with the project's Content Manager.

Standard templates will be available in both Daisy and the Redmine wiki for use on regularly produced documents.\

Under relevant parent projects, templates will be available for regularly used wiki pages such as outlines, meeting notes, and standard OIT notes.

Daisy templates will be available under their relevant collections. Content creators developing documents in Daisy will be encouraged to use these templates as an aid to their development.

Ideas in their early stages need to be recorded; however they're not yet ready to be included in Daisy. These items can easily be entered and stored on the Redmine wiki for the project they're associated with.

Maintenance and editing of these pages is the responsibility of the content creators. The Redmine Wiki will receive very little moderation beyond Content Manager suggestions for what information should be fleshed out and included in Daisy.

While some information will be appropriate to develop further and include on Daisy, other documents will lose their relevance or merely exist in a historical context. This information will remain in the Redmine Wiki with the relevant project and be retired with it.

When the ideas of a given Redmine page have reached a level of development that the content creator can 'flesh them out' into a publish-ready document, the content will be revised for inclusion in Daisy.

When the ideas, brainstorming, and/or outlines of a document are developed sufficiently that they can be drafted to a coherent document, they'll enter this drafting cycle. That's not to say these documents must be completely fleshed out or ready to be publish-ready to move into this phase; on the contrary, they'll be fleshed out during this process.

When the content creator is ready to formalize their work they will create a new Issue in Redmine. The type will be set to Document, a brief description added, and the ticket set to the content creator while they finish their first draft.

To help the content creator organize their ideas an outline is strongly encouraged. The ideal program for outlining is Open Office Writer, however Daisy can also be utilized.

First drafts are the premiere attempt of the content creator at making the document, and the author should let their ideas flow as freely as possible. To help them stay at ease the author can feel free to use either Daisy or Open Office Writer.

Those using Open Office will want to review the guidelines in the Software section of this document to ensure an easy transition to Daisy.

When the content creator has completed a draft they will submit to their projects Content Manager for review and feedback via the Redmine Issue ticket. To do so they will assign the Redmine issue related to the document to the Content Manager and provide the document one of two ways depending on the way it was drafted:

The link will be included in the update where the content creator requests the document to be reviewed.

The most recent copy of the document will be attached to the Redmine issue when it is assigned to the Content Manager reviewing it.

The Content Manager will review the document for consistency, adherence to documentation standards, content, and structure. They will provide feedback, either written or verbal, to the content creator and assign the Redmine issue back to the content creator.

The cycle of content creation, submission to the Content Manager, feedback, and revision will continue until the content creator and the Content Manager agree it is ready for publication.

As different content creators will require more or less revisions it is not possible to give a definite time frame or number of revisions after which the document should be transferred to Daisy. As a rule of thumb, when drafts reach in-line revision where the majority of content has been created, the document should be moved to Daisy if it isn't already.

If the content creator is not comfortable making this transition they may assign the Redmine issue to the Content Manager with the request to do so.

In the initial transfer to Daisy the document will be kept in the DRAFT status.

When revisions have been completed the status of the Daisy document will be updated to PUBLISHED. Any source document housed on the Redmine wiki will be retained for historical reference; however a header will be added to the top of the page with a link to the Daisy repository document and any relevant comments.

To demonstrate this process, the Documentation Strategy document will be used as an example:

Before writing, the content creator of the Documentation Strategy outlines the ideas of the document in Open Office Writer. It is a loose sketch, yet they are sure to use the Styles and Formatting tool for an easy conversion to Daisy after the document has been written

Once outlined, the content creator of the Documentation Strategy is ready to develop the first draft. The headers are already outlined in Open Office Writer, so they focus on developing each section. They create a documentation issue in Redmine and assign it to themselves.

After finishing the first draft of the Documentation Strategy, the content creator is ready for feedback. They attach the draft to the Redmine Issue and assign it to the Content Manager for their project with any important notes written in the ticket.

The Content Manager reviews the document and provides written or verbal feedback depending on the content creators needs and preferences. After feedback has been given the Redmine Issue is returned to the content creator while they make revisions.

With feedback from the Content Manager, the author of the Documentation Strategy revises the document. After making another request for feedback via the Redmine Issue the content creator and Content Manager agree it's ready to be converted to Daisy. Conversion to Daisy

The creator of the Documentation Strategy feels confident making a new document in Daisy and proofing the headers for proper formatting. They collaborate with the Content Manager on formatting the table properly and save it in the SPS IT Collection to ensure the right people will have read access to it. The Daisy Document is marked as a DRAFT.

Minor edits and in-line revisions are made in Daisy and the Redmine Issue stays assigned to the content creator. The content creator and Content Manager agree the document is complete, the status of the Daisy document is set to PUBLISH to allow others to read it, and the content creator closes the Redmine Issue as resolved.

All reference images will be stored in PNG or SVG format in Daisy.

Reference documents such as spreadsheets, flow charts, and any 'living' reference documents that are utilized by multiple people will be stored in Daisy. (Ex: The 'Whose Who' spreadsheet of individuals in the Sahana community).

In-line developer documentation will be governed by the In-line Document Standards. The workflow for inclusion in the general documentation is as follows:

Developers will create in-line developer documents as they program as outlined in the in-line developer Documentation Standards.

When a module is completed testing and the documentation able to be generated, the content creators will used Doxygen to generate the relevant text.

A Redmine issue with the type 'Documentation' will be used to track the progress of the document. The content creator will submit a new Redmine issue with the document for review attached to the project's Content Manager.

The Content Manager will review the document for adherence to the in-line developer Documentation Standards and return the Redmine issue to the content creator if necessary.

When the Content Manager and content creator feel the document is ready for publication the document will be converted to Daisy.

If the content creator is not comfortable making this transition they may assign the Redmine issue to the Content Manager with the request to do so.

In the initial transfer to Daisy the document will be kept in the DRAFT status.

When revisions have been completed the status of the Daisy document will be updated to PUBLISHED.

One advantage of Daisy CMS is its approach to document storage and display. All documents are stored in a non-hierarchically structured server and ported based on collection tags and the engine displaying them. The following are display structures created for the initial formation of Daisy CMS at SPS.

The Daisy Wiki is the built-in viewer for Daisy CMS. It allows a customizable view of the primary Daisy features, administrative use of the ACL, and book publishing.

The SPS Agasti team does not require immediate access to all documentation and it is helpful to customize a side bar with relevant SPS Agasti documentation.

OEM's training materials do not require a log-in to be viewed; however they do need to be filtered for viewing. This can be accomplished via an external training website or a customized view of the wiki.

Upon expansion to SPS IT beyond the Agasti project a custom view of the Wiki will be made available with side bar menus for every course and an administrative menu for SPS Admins.