Quick Tips in Managing Development Artifacts
Help Implement Solutions for Documents Written By SMEs
Jan 10, 2009
While technical writers have their own methods and tools in writing and maintaining documentation for external distribution, other team members are documenting projects too. If the documentation written outside of the technical writing team (requirements, specifications, general coding notes) is done without a formal process, help set the standard.
The goals for this effort should be to:
- Minimize the possibility of duplicate documentation on individual hard drives or on a shared drive
- Centralize information so that the latest revision is accessible
- Provide an auditable trace of previous revisions
- Enable instant collboration with minimal fuss for SMEs
- Ensure that proprietary and confidential information is secure
- Offer a seamless and painless transition to a new methodology (as a good neighbor practice)
- Find a method that helps the technical writing team communicate with SMEs
Read some of the possible solutions offered below. Assess your team’s workflow, available tools, and budget. Also consider the impact of open source software in your organization.
Source Control Tools
A check-in and check-out control enforced by source control tools ensures that the latest revision is available centrally. Icons will change to show that a document or file has been checked out, flagging users to wait to make edits. Communicate this as the home of development docs, and so it will be.
Examples: Collabnet Subversion, Serena Dimensions, Microsoft Visual SourceSafe
Pros: Tools should be immediately available (your team's code repository). Source control applications provide a strong ability to trace who has made changes and to access older versions of the file.
Cons: These repositories may be limited to developers only. Without naming conventions, the repository may become as cluttered as a shared drive. There is minimal help in showing the differences between document versions, although the use of notes can cure this. Technical writers may still want to edit/format Word documents.
Document Management Software
Document Management Software (DMS), such as Microsoft SharePoint, manages major and minor versions of a document. Username and notes are captured, enabling quick assessment of what has changed between revisions. Moreover, DMS provides review workflows – where the Technical Writer may be counted on as the documentation SME.
Examples: Microsoft SharePoint, Alfresco Document Management, KnowledgeTree
Pros: You may already have SharePoint as a resource. Files cannot be destroyed or edited without granted permission. Security can be defined.
Cons: As with using source control applications, naming conventions may need to be applied. Assumes formal documentation is created and that a check-in and check-out solution is desired. Can be a costly alternative.
Enterpise Wikis
Wikis provide quick access to information on page – without the need for separate files. However, standard Microsoft Office files may be embedded or attached to wiki pages as needed. Wikis offer ad hoc collaboration among all users on wiki pages, which may be secured to specific users and groups as necessary.
Examples: Atlassian Confluence, PBwiki, Twiki
Pros: Provides tools to instantly start collaboration. Plug-ins may be installed for further workflow customization.
Cons: May be costly and difficult for all users to immediately adopt. This is a change in workflow for users accustomed to shared drives and Word documents.
 |
