[82] in Kakapo Windows Team
Documentation Workflow Proposal for Managed Windows Products &
daemon@ATHENA.MIT.EDU (Kerem B Limon)
Thu Aug 28 14:47:53 2003
Message-Id: <5.2.0.9.2.20030828120054.10c90210@hesiod>
Date: Thu, 28 Aug 2003 13:58:39 -0400
To: Kakapos at MIT <kakapo@mit.edu>
From: Kerem B Limon <kerem.limon@MIT.EDU>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"; format=flowed
Enclosed is the text of the documentation workflow I proposed today in the
meeting, for all to review.
We agreed that it's easier to just add Tim Brennan and Elise Riordan to the
kakapo@mit.edu mailing list for them to see the document submissions,
instead of remembering to CC: them each time. I will deliver the Kakapo
intro and heads up to Tim and Elise.
We also agreed that we will CC: all document-related discussion to Kakapo
such that we can all follow it up, if necessary, retroactively.
BTW, the MSI XML info Joe presented is located at
http://web.mit.edu/pismere/msilist/msilistpresentation.htm
Regards,
Kerem
--Enclosure--
Documentation Workflow Proposal for Managed Windows Products & Services
v0.1 - Kerem B. Limon
The following proposed guidelines define the workflow for the development
(production, review, and publication) of documentation and interfaces for
managed Windows Products & Services at MIT.
--Location--
The location of the Managed Windows Products & Services documentation will
be under http://web.mit.edu/windows/server/ until otherwise agreed upon by
Kakapo, and unless there is a compelling reason for the document to reside
elsewhere in the IS Web hierarchy (e.g. a request form that is processed by
a team/sub-team in IS and needs to reside in their corner of the IS Web
space for operational/administrative reasons).
--Production and Development Mirrors--
There will be a development mirror of the documentation kept under
http://web.mit.edu/windows/server/dontindex/ and ACL'd via MIT personal
certificates, restricted to the Kakapo members, the technical writer and
TPS staff, the IS Web Master and team, and other individuals that are
stakeholders in this documentation who are not represented in any of the
previous groups. The ACL membership will be maintained by Kakapo, and in
most all casees should be a trivial matter.
This mirror will be used solely for the purpose of final cross-check of
documents that are in final candidate/draft format and are ready to be cut
over to the production publication space. A technical writer from TPS
assigned to the manager Windows products & services documentation efforts
will maintain this mirror.
--Outline and Organizational Structure--
The Windows 2000 Domains, Workgroups, Servers Delivery Project Team, led by
Kerem, will submit to Kakapo an initial version of the overall
documentation and interface outline developed during the Delivery Project.
This outline will be the starting point, along with the recently deployed
matching Web site framework located at http://web.mit.edu/windows/server/.
Through the wrap up and transition period of the Windows 2000 Domains,
Workgroups, Servers Delivery Project, Kerem will assist Tim Brennan in his
role as IS Web master with the integration and optimization of this outline
in a manner befitting the rest of the IS Web site organization.
The outline will be located at
http://web.mit.edu/windows/server/dontindex/outline/ as part of the
development mirror and under the same ACLs.
This outline should reach a fairly stable point within the next 2 - 3
months, after which the upkeep of the outline will become a more routine
and incremental task. At this point, with help from Tim Brennan, the IS Web
Team, and Training and Publications, permanent upkeep responsibilities for
the outline will be assigned by Kakapo.
The outline will be used to manage the documentation effort and help
identify and prioritize the development of needed documents. Each item in
the hierarchical outline will be assigned to reflect the following details:
o Name of document and/or very brief description if deemed necessary;
o URL or other location for the document;
o Name of the *owner* for this particular document;
o Name of the current *author* of this particular document;
o *Status* of this document;
o Date this information was last updated, and by whom.
The name, description, and URL concepts, as well as date of last update and
name of updater are intuitively obvious. Within this context, "owner" is
described as the individual(s) or team(s) who provide the associated
products and services for which the said documentation is produced, and who
are ultimately responsible for originating it. The "author", on the other
hand, refers to the actual individual(s) who "pen" the document itself, so
to speak, and may or may not be one of the "owners", but in most
circumstances, will be. This should allow for maximum flexibility in the
assignment of original production and drafting responsibilities, especially
when transitioning potentially to a TPS-maintained schema in the long run.
The "status", on the other hand, reflects briefly the current state of the
document--it can be
o "missing" for documents that are needed;
o "in production" for those being written;
o "draft" for those that have been, but not approved or finalized;
o "complete" for those that are completed and reviewed; and
o "published" for those that have actually been published on the Web or
wherever the location is.
--Overall Management--
The overall management of the outline aside from the mechanical tasks of
keeping the outline itself, require technical expertise that is not
currently present within the IS Web and TPS teams. Until a more requisite
level of expertise is developed, Kerem will assist Tim Brennan and
associated with technical consultation needs. In the long run and once the
workflow has begun flowing, Kakapo will be made available as a consulting
resource to Tim Brennan and associates for clarification of technical
issues and organizational questions about content. Kakapo will need to be
responsive to these needs.
Once a need or missing document has been identified, Kakapo will be
responsible for compelling (and making available resources, as necessary
to) the designated owners of the documents.
--Technical Writing, Formatting, Styling, and Final Production--
The final formatting, styling, and production/publication of the documents
will be the responsibility of a technical writer from TPS assigned to the
managed Windows projects & services, who currently is Elise Riordan until
the end of 2003. It will be the responsibility of the technical writer to
convert documentation received from and drafted by the owners and original
authors, to a format suitable for publishing on-line and consistent with
the rest of the documentation and the outline hierarchy. The technical
writer may also be called upon by owners to assist in drafting an authoring
tasks, but owners will be responsible for providing the responsive
technical assistance the writer may need in these cases.
--Ownership & Production Responsibilities; the Drafting Process--
The designated owners of the documents are ultimately responsible for
originating at least an initial draft of the documents assigned to them.
These may come from previously existing documents or commissioned to be
developed from scratch. The owners can draft the documents themselves, or
consult with the outline managers and Kakapo to seek authors to help
produce the drafts, including the technical writer assigned to the project.
--Formats and Style for Production of Documents--
There are no specific guidelines for document formats, except that owners
and authors should strive for simplicity and ease of conversion for
ultimate Web publishing. Since certain contingents of documentation may
pre-exist in a variety of non-Web formats such as Microsoft Word documents,
it will be the responsibility of the technical writer assigned to the
project to convert these, as mentioned above, to a format suitable for
publishing on-line and consistent with the rest of the documentation.
Owners will negotiate with the technical writer on an individual basis for
details.
The primary goal for the next 6 to 12 months should be the production,
review, and publication of the necessary documents in a reasonably
accessible format, as soon as possible. Once the documents are in place
and/or the technical writer(s) have the opportunity, the documents should
be updated to match the new IS styles for IS Web pages to ensure
consistency with the rest of IS documentation. Related documents within the
IS Web hierarchy related to managed Windows products & services, but hosted
elsewhere should ultimately also be updated to match the style, though this
remains a lower priority.
--Review Process--
Once a draft document is complete, the owner(s) and author(s) will make it
available to Kakapo for internal review and announce the document, where it
fits in the outline, and draft location (a URL, an attachment, etc.) to
Kakapo via e-mail. Kakapo members will review the document and will have a
5 business day grace period to suggest changes.
If there are minor changes made to the document (correction of typos,
grammatical errors, minor edits, etc.), these will not count against the
grace period.
If there are more extensive changes made to the document (reorganization of
the document structure, major rewrites of portions, etc.), the draft will
be considered returned to the owner(s) and author(s), who will then be
responsible for the revisions requested and submitting a new draft. A new
grace period will apply when the new draft has been submitted.
All discussion pertinent to the document should proceed within the Kakapo
space and the Kakapo mailing list should be CC:'d on all updates and
discussions. If necessary, relevant individuals/teams outside of Kakapo may
be invited to participate in the discussion to render advice and opinions.
If, at the end of the 5 business day grace period, there are no extensive
revisions requested or objections raised, the document will be accepted by
default.
--Publication Process and Final Cross-check--
Once the document has been accepted. The technical writer will then move
ahead and proceed with the conversion and publication of the document at
its designated location in the documentation hierarchy. The technical
writer will then inform Kakapo by e-mail once the document has been
produced and ready to be published, pointing to the final draft of the
document in the development mirror of the managed Windows products &
services documentation under http://web.mit.edu/windows/server/dontindex/.
If there are no last minute corrections and objections within a 1
business-day period, the technical writer will proceed and cut over the
final document to the published production location under
http://web.mit.edu/windows/server/.
