First of all
Thanks a lot for opening this document and welcome to the group of actual or potential procedure authors!
We want to provide procedures with a consistent look and structure to the operators and this document should serve you to create your own procedure for EuXFEL following the developed guidelines.
You have questions or ideas how to improve things? Please contact Matthias Scholz or write a comment at the end of the page.
If you have knowledge about a very important tool, device or procedure but you do not have time to write it yourself in Confluence. Let us know and we will find a solution to prepare the procedure!
Lets clarify a few things first:
Who should or could write procedures?
Anyone who nows how to carry out a specific task, how to operate a software tool or a device of EuXFEL is encouraged to write a procedure based on his/her expertise.
What is the aim of the procedures?
We need precise procedures for many task being important for machine operation. In some cases it is to avoid damage of equipment, to reduce setup times and to verify that we deliver constantly good performance no matter who is operating the machine.
Where should you store the procedures?
The confluence space 'XFEL Operations' where all released procedure are stored is editable only by a small group of colleagues. Thus it is suggested to write a procedure in Confluence using your own space. Upon completion we can copy that page to XFEL Operations and add you procedure to the tables on the overview page. All authors will have permissions to maintain their procedure there.
How should the procedures look like?
The idea is that all procedures listed in the table 'List of operation procedure' on the overview page should follow the same style. This hopefully makes it easier for the operators to find one's way through the task. For that reason this style guide that you are reading right now exists. All other procedures, like those listed in the table 'List of system procedures' can use the same style guide but it is not required.
Is there a blueprint for procedures available?
Yes of course there is a blueprint for procedures available!
How to start writing a procedure
It is recommended to start either with an existing procedure of your own or with the blueprint available on Confluence. In that case you have already the procedure's structure with the header as well as with all headlines, listings etc. included.
The procedure header
Please fill the header table with the named information.
- Titel of your procedure which makes clear what the procedure is for.
- The ID can be added later after copying the procedure to the XFEL Operations page.
- Your name as the responsible person. The Confluence jargon is to write @ followed by you name. That establishes a connection to your Confluence account.
- Please start with release version 1.0. The next updates will then be called 1.1, 1.2 etc. The first digit should only change after major modifications. This would be the case e.g. when the old procedure can not be carried out any more due to hardware modifications at EuXFEL. Also when a new server or tool takes over part of the procedure, the first digit can be changed.
- The last modified field should be filled out with the current date.
- As a rule of thumb, add 6 month to the current date and write that down as date for the next review. In case you know already that you procedure will change in 2 month, marked that date accordingly. On the other hand, procedures that are rarely used, like those only used for start-ups, should be preferably 'reviewed before use'.
- The status should be 'Released' as soon as the procedure is published on the XFEL Operations page.
- Possible status are: 'DRAFT' for work in progress, 'RELEASED' for verified and tested procedures and 'OUTDATED' for previously 'RELEASED'-tagged procedures that need an update.
Under Scope and goals you should write a brief description of what can/should be achieved with this procedure. Together with the title it should be clear to every operator to what the procedure will lead to.
The Application list summarizes when (i.e. under which circumstances) the procedure is to be used. This should again help the operators to differentiate whether this procedure is the right one to be applied.
Roles and responsibilities might be clear in most cases. Meaning that the operators are carrying out the procedure. However, like in the example shown on the right hand side, it might be that there has to be a decision made by the run coordinator or shift leader before the procedure can start.
The following table of content is a Confluence feature and will be added automatically if you follow the instructions on this page
The headlines like 'Header', 'Scope and goals', Application', 'Roles and responsibilities' or finally 'Procedure' should be selected as 'Heading 1' in the dropdown menu on the top left of the page. In addition the headlines should be in bold letters. All other content in the header should be 'Paragraph'. Of course these rules are considered in the blueprint.
The procedure's flowchart
The idea is to provide an overview of the procedure to the operators. The flowchart might provide enough information for very experienced operators to carry out the procedure. The position of the flowchart is in the top right corner next to the header.
It is suggested to write the procedure first and to draw the diagram afterwards. A few design hints are given in the diagram on the right hand side. You will find the same in the blueprint where you can just edit it. In case it is necessary to generate a new diagram, klick on the '+' in the Confluence header and select diagram. In the pop up window, select either one of your previous diagrams or 'Basic'.
Of course it is also possible to copy diagrams like the one on the right hand side and paste it to the new procedure.
Please follow the instructions in the diagram on the right hand side and chose the flowchart symbol's shapes and colors accordingly. More information about flowcharts in common can be found at Wikipedia.
It is recommended to use the DESY colors for the procedure's flowcharts: Orange (RGB 242, 142, 0), Cyan (RGB 0, 166, 235), grey (119, 119, 119). The default font size in flow charts is 18 px.
Please adjust the flowchart's size such that it does not dominate the page more than necessary. To do that, click on the diagram and select the size in the popup window. Typically the smallest size fits just well.
- The procedure's Confluence pages are divided in two equally sized columns.
- The left column contains the single steps in some details that should be enough for most operators.
- The column on the right hand side is there to add all details that are required such that all colleagues can carry out the procedure.
- Please use the expandable windows as in the blueprint.
- The right column can also contain screenshots.
- Every single step of the procedure should be written in a new section. More details about that can be found in the blueprint.
- The numbering of each section's headline has to be added by hand.
- All steps and sub-steps have to be numbered such that the operators can easily report to the author at which position they got stuck etc.
- Keep the descriptions as short as possible and use common terms.
- Do not formulate ambiguously but give a clear step-by-step guidance.
- Use active voice in your descriptions.
More information how to structure the procedure can be found in the prepared blueprint.
The version control is taken over by Confluence.
Please use the edit field in the bottom right corner to briefly describe the modification you made before updating the page.
It is then possible to review and reload older versions of the page by clicking on 'Page History' in the drop down menu behind the three dots in the top right corner of the Confluence page.
An this is how the version overview looks like:
it is even possible to compare two selected versions of the document by clicking on the 'Compare selected versions' button on top of the page!
- No labels