¶ Information Management
At Phanous we create a large amount of digital information. This information is used for the day-to-day work of the organization, as well as providing a record of decisions and actions needed for accountability and legal compliance. The task and responsibility ro create, manage and store this information is collaboratively shared by all Phanous members.
The purpose of this document is to,
- Provide some simple guidelines for managing digital information.
- Help you to make decisions about how to manage and store particular types of digital information.
- Create unified standards of documentation across Phanous for effective decision making and knowledge sharing.
¶ Documentation Philosophy
Documentation is a fundamental part of our working culture at Phanous. We document for effective knowledge sharing and to ensure that our decision making is agile, consistent and systematic. The Phanous documentation guidelines is based on a 3-tier system philosophy. The three tiers of guidelines are;
- Principles
- Structures
- Templates
Documentation principles refer to the general guidelines and issues we look to maintain across all our documentations. These will be independent of the context of the document. Any guidelines identified as a documentation principle means it applies to all documents produced at Phanous.
A document strcuture refers to a framework for documents with similar content, for example reports, papers, meeting agendas etc. Structure guidelines apply to all document with content matched with the respective scope of the structure.
Document templates are prepared for specifc types of documents. This will be either in case of regular documents required to be generated repeatedly, or in case of documents which are essential to be prepared to the correct format.
The 3-tier system is illustrated in Figure 1
Figure 1: 3 Tier documentation guidelines at Phanous
¶ How to use the guidelines
The system is bottom-up. This means when you want to create a document, you should first check to see if there is an existing template for it. If not, you may consider creating one (we talk about this later) or refer to the next level up guidelines about how you should structure your document (according to the category of document). For example, all reports (with or without existing templates) must adhere to certain structural guidelines.
If for the category of document you are looking to create there are no structural guidelines, then you may once again consider creating a set of structural guidelines, or else, refer to the overall principles of documentation to prepare your document.
If you decide you want to create a template for your document, make sure of the following,
-
Making a good template takes time and effort. Therefore templates are only recommended to be created for frequently generated document, or for documents which (may not be frequently generated) must have specific formats (e.g. financial docs).
-
Consider all the future users who will be using your template. Is the template easy to use? clearly understandable? does it require special technical skills, or use of special codes?
-
Do your research on whether there are pre-existing standards of documentation for the type of document you want to generate a template for. If so, please study and use them.
-
Try to collaborate as much as possible with others when making a new template. The more people collaborate with you, the less chance you have missed something out.
If you decide to prepare strcutural guidelies for a new category of documents, please pay attention to the following,
-
Keep it simple, to the point, and effective. Guidelines at the structural level should not be cumbersome or with too much detail.
-
The structural guidelines you generate will be used in the future to generate document templates. Consider yourself as the next person who would be using the guidelines to generate a template. Are the guidelines sufficient and clear to generate a good template?
-
Do your research on whether there are pre-existing standards of documentation for the category of document you want to generate guidelines for. If so, please study and use them.
-
Try to collaborate as much as possible with others when making a new template. The more people collaborate with you, the less chance you have missed something out.
Figure 2: How to use the Phanous documentation guidelines
¶ Scope of documentation guidelines
Phanous documentation guidelines covers major scopes related to the production and maintenance of Phanous documents. This is categorized into the following five scopes.
-
Editing is related to editorial processes.
-
Formatting refer to how a document is organized and its structure.
-
Contents is related to what should (and perhaps should not) be contained in the document.
-
Referencing outlines the proper use of other people work.
-
Post-production covers the processes that kick in once a document is created and how it should be maintained.
Table 1 illustrates the items related to each scope and whether they are tier 1 or tier 2 guidelines. Obviously in a template all items should be specified.
| Scope | Items | Tier Relevancy |
|---|---|---|
| Editing |
|
|
| Formatting |
|
|
| Contents |
|
|
| Referencing |
|
|
| Post-production |
|
|
Table 1: Scope of the documentation guidelines
¶ Documentation Principles
Our principles of information management covers creation and management of documents. These guidelines are partly based on [4] and [5]. Recall these are context-free and apply to all documents generated.
¶ Creating Documents
¶ File names
Agree on a logical and consistent way of naming files within your lab/team. Naming files consistently also helps to prevent version control problems if you need to work on files with other people.
To make tracking and sharing easier across various operating systems and between people, use the following guidelines,
- Use English to name your file. Do not use persian characters. Do not use Finglish.
- Keep file names short but meaningful.
- Use underscores to delimit words (snake_case). Do not use spaces, CamelCase, kebab-case, etc.
- When including numbers, use *leading zero(s) so that files are listed in their natural sort order.
- If using a date in the file name use the Hijri date in the international form i.e. YYYYMMDD.
- Include the version in the filename.
- Do not rely on folder names to give your filename context (think if they would still make sense if the file is moved elsewhere).
¶ Saving files
Consider the following points about saving files,
-
As a default, you should use a cloud service to store your files with the ability to share files, recover deleted files, and version control.
-
If you do have to store a local copy of your file, make sure you update it on the cloud storage as soon as possible.
-
If your local copy is in conflict with the cloud version, you must resolve the conflict as soon as possible. Do not keep a conflicted version of the file on the cloud storage.
-
You have the responsibility to ensure that the proper rights and accesses are granted for the file. Only people who need access to the information should have it (See the data protection and data classification guidelines).
-
Only use a file format which is accessible and easy to use for all people who are expected to collaborate and work with on the document. As a general rule, (where applicable) you should also a store a PDF version of the final version of your document (for other people to view the content).
-
Choose a function-based approach to naming folders, give folders a meaningful name.
-
Keep folder names short to avoid very long file paths.
-
Try to achieve a balance between folders containing huge numbers of files, and folder structures many levels deep. A good rule of thumb is that most people should reach the information (file) they want in 5 or less clicks.
¶ Data Protection
As a Phanous researcher, or as a Phanous administrative staff, you might have access to restricted employee personal data or company data. It is very important that you take due care and precaution to protect this data.
The following tips will help to keep confidential or senstitive data secure,
- Do not communicate personal or restricted data via unencrypted email.
- Do not take personal or restricted data home on physical storage devices such as USB sticks or the hard drive of your device. All such data must be stored on a cloud service that you can access outside Phanous if you need to work on it.
- Take adequate measures to ensure that unwarranted access to your computer and data accounts is blocked.
¶ Data Classification
The information we hold at Phanous is orgniazed under a classification system which facilitates proper control and protection of data. These are,
- Public
- Open
- Confidential
- Sensitive
Each type of data had a different risk factor attached to it and the impact on business is accordingly different. See the following tables for a more detailed description of the classifications.
| Item | Description |
|---|---|
| Classification | Public |
| Definition | Available for public access |
| Impact of leak | Not applicable |
| Examples |
|
Table 2: Public data classification
| Item | Description |
|---|---|
| Classification | Open |
| Definition | Available for all Phanous members |
| Impact of leak | Low branding or financial damage. Minor privacy breach for an individual |
| Examples |
|
Table 3: Open data classification
| Item | Description |
|---|---|
| Classification | Confidential |
| Definition | Restricted access for a controlled group of people |
| Impact of leak | Medium branding or financial damage. Intermediate privacy breach for an individual. May make it less likely that Phanous would be trusted with similar information in future. |
| Examples |
|
Table 4: Confidential data classification
| Item | Description |
|---|---|
| Classification | Sensitive |
| Definition | Restricted access for a controlled group of people |
| Impact of leak | High: Could substantially damage our reputation, have a substantial financial effect, or result in a serious privacy breach to one or more individuals. |
| Examples |
|
Table 5: Sensitive data classification
¶ Managing Documents
¶ Version Control
Version control is extremely important both for collaborative and non-collaborative documents. Version control,
- ensures people are working on the last edition of the document.
- allows for a history of changes to be gathered which facilitates recovery of information.
- makes labeling of documents easier and avoids lost time looking for the right information.
Document version control uses incremental numbering or lettering of file names to show changes to a document or file. It allows you to keep track of revisions and removes confusion when different versions of the same information exist.
Phanous general guidelines for document version control are as follows,
- Include the version in the filename and/or folder name.
- Assign numbers after ’v’ to successive versions e.g.filename_vx.y.ext (ext is the file extension).
- Use x to denote major document changes and y to denote minor changes.
- If you use a software which has automatic version control (i.e. previous versions of the file are available) you do not need to explicitly store previous file versions. Note that automatic version control is different to back up and recovery. Most cloud storage solutions (e.g. dropbox, onedrive) do not have version control.
- For formal documents which may be subject to revisions over a long period of time (for example reports, handbooks etc..), it may be useful to include a document control sheet on the first page. The control sheet should record brief details of the revision process, including version number, who made the changes, when and why.
¶ Collaborative editing
Collaboration is part of our vision at Phanous, and we exercise it where possible. Our wiki, Gerd is a great example of collaborative work created by Phanous members. Collaborative works should have an owner. The job of the owner is to manage the collaboration effort by,
- selecting a suitable collaboration platform suited to the content.
- ensuring proper rights and accesses are given to people who will be working together and none other.
- resolving editorial conflicts.
- preparing the final version of the document.
- document version control.
- ensure uniformity and consistency of content and formatting.
In order to have effective collaborations the following hints and tips are useful,
As an owner;
- Make sure all potential collaborators can use the software platform you choose.
- If you want to dismiss a comment, let the person know why the comment is not applicable.
- Make sure people are clear what is the latest version of the file they should be working on.
- If you are not using a platform with file history, make sure you have proper arrangements for backup of the content. People always make mistakes.
- Control the file names and locations are correct and in accordance with the guidelines.
- When you close the work and create the final version, let people know about it and send them the final version.
As a collaborator;
- Make sure you are working on the latest version of the file(s).
- It is good practice to let others know about the changes you have made (for example leaving comments etc).
- Co-ordinate any major changes with the owner.
- Keep your edits consistent with the style and format of the document.
- Avoid working offline. If you have to work offline, make sure you do not overwrite other peoples changes when uploading your content.
¶ Formatting; identity
Information created at Phanous should be objectively identifiable. The identification requirements vary depending on the document. A brief set of guidelines are as follows,
Public documents released by Phanous (e.g. reports, presentations, etc) should,
- display the Phanous logo.
- have Phanous contact details.
- have release date, version and copyright disclaimer.
- refer to the organization as either ‘Phanous research and development centre’ or, ’Phanous’. All other forms (e.g., Phanous research centre, Phanous centre,..) are not acceptable.
- unless there are specific reasons, not be editable.
Phanous documents for general internal use (e,g, directives, handbooks, reports, etc) should,
- display the Phanous logo.
- identify who is the document owner to whom feedback and comments should be addressed.
- have release date and version.
Single purpose task based documents (e.g. meeting agendas,draft papers, etc.) should,
- identify who is the document owner to whom feedback and comments should be addressed.
- have release date and version.
¶ Contents; Clarity
English is the official language for doucmentation at Phanous. In the future, we aim to obtain the Crystal Mark and the Internet Crystal Mark accreditation from the Plain English Campaign.
The Plain English Campaign has several editing, proofreading and writing guides and tools. An excellent short guide is the How to write in plain English. Here are some tips from the guide,
-
Keep your sentences short;
- Recommended average sentence length is about 15-20 words.
- Vary your writing by mixing very short sentences with longer ones.
-
Prefer active verbs;
-
Consider the example: Peter ( subject ) watched ( verb ) the television ( object ). With a passive sentence, the object becomes the subject and the subject becomes the object. The television ( subject ) was watched ( verb ) by Peter ( object ). Or the example: ’The riot was stopped by the police’ (passive) versus ’the police stopped the riot’ (active). The passive form is longer because we have to add ’was’ and ’by’.
-
Active verbs give shorter, crisp and professional sentences.
-
Passive verbs can be confusing, make sentences longer and make writing less lively.
-
Passive verbs may be used to make something less hostile (’the bill has not been paid’ is softer than ’you have not pain the bill’), to avoid taking blame (’a mistake was made’ versus ’we made a mistake’) or when it is not clear who the doer is.
-
Aim to use 80-90 percent of the verbs in the active form.
-
-
Use ’you’ and ’we’;
- Try to call the reader ’you’ (as opposed to ’the applicant’, ’the supplier’ etc..). For example: ’Applicant must send us’ versus ’you must send us’, ’advice is available from’ versus ’you can get advice from’.
- Use ’we’ Phanous, your team, lab etc.
-
Use words that are appropriate for the reader;
- Say exactly what you mean, using the simplest words that fit.
- Jargon is a type of language that is only understood by a particular group of people. Avoid jargon for general documents.
- In general, keep to everyday English whenever possible. And again, imagine talking to your reader across a table.
-
Don’t be afraid to give instructions;
- Imperatives (like ’Sit’, ’Brush your teeth’) are the fastest and most direct way of giving someone instructions. For example compare ’Writers should aim to be punchy’ with ’Be punchy’, or ’The packet should be removed from the box. The contents should then be placed in the oven’ with ’Remove the packet from the box. Then place the contents in the oven’.
- You can use ’please’ before commands to make them less harsh.
-
Avoid nominalizations;
- A nominalization is a type of abstract noun. For example: ’Complete’ ( verb ) versus ’Completion’ ( nominalization ), ’Provide’ ( verb ) versus ’Provision’ ( nominalization ).
- Nominalizations are often used instead of the verbs they come from. And because they are merely the names of things, they sound as if nothing is actually happening in the sentence. Like passive verbs, too many of them make writing very dull and heavy-going. For example: ’We had a discussion about the matter’ versus ’we discussed the matter’.
-
Use lists where appropriate;
- Lists are excellent for splitting information up.
- There are two main types of list. A list that is a continuous sentence with several listed points picked out at the beginning, middle or end. And a list of separate points with an introductory statement.
- When each point is a complete sentence, then each one starts with a capital letter and ends with a full stop.
- With a list that is part of a continuous sentence, put semicolons ( ; ) after each point and start each with a lower-case letter.
- Make sure each point follows logically and grammatically from the introduction sentence to the list.
-
Myths (stuff you thought you cannot do but are perfectly ok);
- You can start a sentence with and, but, because, or however.
- You can split infinitives. So you can say ’to boldly go’.
- You can end a sentence with a preposition.
- You can use the same word twice in a sentence if you can’t find a better word.
¶ Documentation Templates
The following templates are available for use by Phanous members. We encourage you to add your templates for the use of others,