HERMES Wiki Guidelines

Welcome to the HERMES wiki!!

WE WANT YOU TO HELP CONTRIBUTE TO THE WIKI! That means you don't have to ask anyone's permission to edit any page! All you need is a wiki account, which you create yourself. However, to maintain order, we have a few requests.

• Page missing?
  • Then make a new one!
• Content Missing?
  • Then add it! Or, if you don't know the information yourself, add a flag indicating what is missing.
• Content Wrong?
  • Please fix it! Or, if you don't know the correct content, add a flag indicating the content is erroneous.
• Conflicting or duplicate Information?
  • Please email both page maintainers and dtfAThermesDOTdesyDOTde to help us resolve the problem ASAP
• Questions / comments / concerns
  • If you're not sure where else to turn, please email dtfAThermesDOTdesyDOTde
• Problems with non-wiki pages?
  • Add to the list of Bugs on non-Wiki pages to be fixed

Responsibility

One of the main concerns about the wiki has been how content will be monitored and who will be responsible for keeping everything in order. This will happen on two levels:

Documentation Task Force (DTF)

DTF is a small group of people who keep the wiki running - including technical maintenance. DTF is the only user that is allowed to delete pages, roll-back to previous pages, etc. DTF will meet for a short time before the Thursday analysis meetings to review the wiki status and address any issues.

Page Maintainers / Watchers

• {{MAINTAINER_name}} will appear at the top of every page (with the exception of the Category:FreeForAll pages), indicating the current person responsible for the page (not necessarily the original author). This should be an active HERMES member.
  • Page maintainer can be viewed at the top of each page and from the Category page.
• Watching - this maintainer should also have a watch on the page. Watching a page means that each time a change is made to the page the watcher will get an email. Wiki nicely only sends one email noting the page has been changed, and will not send a second email (even if the page is edited again) until the watcher has viewed the page. Also, emails are not sent when the change is made by the watcher him/herself.
  • To set up a watch, be sure you have registered an emailed address (and confirmed it). Then, while viewing the page, click the "watch" tab at the top of the page
  • A list of the pages you are watching can be seen if you log in and then click the "my watchlist" link near the "log out" link
  • Unwatched pages are listed here. These will be periodically reviewed and assigned to a watcher
  • Some pages that are expected to remain unchanged will be maintained and watched by DTF
  • The official page watcher is responsible for checking that any changes to the page are acurate, constructive, appropriate, and in accordance with the rules of the wiki stated on this page.

Catching all pages

Additionally the status of content / pages can be monitored in several ways:

• Each page will have a status, and the pages in each category can be found in the appropriate Category page.
  • Uncatergoried pages are listed and will be periodically reviewed and categorized by DTF
• Text flags will mark where content need to be changed or edited, these flag can be found by searching for them.

Flags 1 = page status

We will use premade templates at the top of each page (and/or subsection) to indicate the page's status to others. One of the following template lines should exist at the top of every non-finished page, and whenever you edit or review a page, change this header:

• {{UNDERCONSTRUCTION_name}}: the page is being actively worked on by name
• {{FORREVIEW_name}}: writers are done with the page, and a review by consultant name is requested
• {{REVIEWEDNOTOK_name}}: consultant name has reviewed the page, and found that some info is either wrong, or else missing and not flagged as such
• {{REVIEWEDOK_name}}: consultant name has reviewed the page, and found that the information is accurate and any missing info has been flagged

The _name part of each tag is an optional argument, use it to indicate who is editing or reviewing. The "name" be also a comma-separated list of names, e.g. if you are the 2nd or 3rd reviewer of a page just add your name to the existing list.

Flags 2 = within text

We will use distinctive words embedded in the text to flag places where other people need to take action. A typical example: you are creating a page on trigger efficiencies and you don't know where to find a list of trigger definitions by year. You need help from an expert, so type the flag-word NEEDEXPERT directly in your text with a brief description of what you need. Experts will later search for incidences of these flags and provide more info.

• NEEDEXPERT: more information is needed to continue writing
• NEEDCODE: a piece of example code is desired
• NEEDTEXT: a reviewer inserts this tag to indicate that information is missing and should be filled in by one of the writers
• NEEDFIX: a reviewer inserts this tag to indicate that the specified information is wrong

Please add a descriptive phrase right after these tags. Reviewers, experts, writers and coders will run wiki-searches for these flags, and the list of matches should efficiently display the essence of each flagged request.

Edit buttons

Always use the subsection edit buttons, if they exist. These are directly on the wiki pages, at the beginning of each (sub)section. Only use the edit button at the top of the browser page when you are creating a new page, if the page has no subsections, or if you are editing outside the subsections (e.g. changing page Category). The reason is to avoid conflicts with other editors: the subsection edit buttons allow you to edit only one section of a page, and not run into people editing other sections.

Preview, Save, Minor Edits

• To reduce the length of the page history and the entries on the Recent Changes page, please make use of the Preview button and mark saves as a "Minor Edit" when appropriate.
• If someone is editing the same page/section at the same time as you and there is a conflict, the differences will be presented for you to resolve.

Example page

Rebecca has created an example of the type of new Analysis Page we are looking for: e/h PID and PIDLIB. The target audience is analyzers who are skilled enough to make an invariant mass peak from the data, namely analyzers who have worked through all the examples in Bootcamp and have some experience making plots. We don't want a ton of pedagogy on these pages; rather we want them to be efficient and complete. For pedagogy, provide links to sections of Bootcamp, or to internal notes, theses, etc. We would like all the new pages to have the following 4-section structure:

• Intro 1-paragraph description of the page's topic, including links back to the relevant sections of the Bootcamp tutorial
• Essentials This is the main part of the page, and should contain everything a current analyzer needs to know about this section to get a result released. This includes exception conditions, e.g. odd things which happened in certain years and could mess things up for an analyzer. Make copious use of links: to key emails, internal notes, uDST documentation pages, etc.
• More Info This is where you can link to old pages, and theses or documents with more detail than an analyzer really needs, but someone might want to know.
• Code Repository We will collect useful codes in these sections.

Creating new pages

• Please read this entire page before creating a new wiki page!! Especially read the notes on Edit buttons and the Preview Save and Minor Edit options
• Before creating a new page be sure that the content you want to add is not already on another page by searching the wiki.
• Before adding a page be sure the content does not belong on an existing page by searching for all keywords related to your content.
• To create a new page, just insert a link to it on some other page. The name of the link will be the name of the new page. The link will show up in red and will appear in the list of "Wanted pages" in the wiki left panel, all indicating that it doesn't exist yet. Please use brief but descriptive names for new pages, such as "RICH PID" or "Merging PS files". Spaces are fine but most other special characters are not (see the right column of the WikiMedia quickref guide). Please do not try to impose any sort of directory structure when choosing names for new pages, e.g. use "RICH PID" instead of some structured thing like "Analysis: RICH PID".
• If you are creating a new page in the Analysis section, start with the Template for new analysis pages: pull this template into the editor and cut and paste the source into your new page. This template sets up the four sections (Intro, Essentials, More Info, Code Repository) that you see in Rebecca's example page.
• If you create a new page please fill in the Intro section IMMEDIATELY with the goal of the page. Even if the rest of the page is empty the intent of the page must be clear to any user who might come across it.
• All pages should have a MAINTAINER, using the MAINTAINER template, as in the Template for new analysis pages
• All pages should be WATCHED, preferably by the author / maintainer
• All pages should have a STATUS

External files (images and codes)

There are two ways to include or reference external files in a wiki page: either upload the file directly to the wiki, or place it somewhere in the /www-hermes/ tree on the PC farm and make a link to it. We have decided on the following convention:

• Codes:
  • Any codes linked to the wiki should be cross checked and ideally from an analysis that has been released. Please note in the code itself the author, date, and a contact email.
  • pieces of code for the Code Repository sections of the wiki pages should be placed on the PC farm. One main reason is that people using the code will most likely use it from the PC farm! You have two options.
    • If you are a member of an established group like "richgrp" or "triggrp", the corresponding group directory within /www-hermes/html/groups/ is the perfect place to store your codes. If you have very large data files, it is better to put them in a group area on /group01, then make a symlink to them in the /www-hermes/html/groups/ area.
    • A new area has been setup on the PC farm for code storage: /www-hermes/html/CODES/. This area will function much like the working PLOTS area: the CODES area and its subdirectories have group-write permission, so you can copy there at will. We will try to structure it by subject-area rather than by name; use directory names similar to those of the Wiki's Analysis pages. The URL address of your files will be http://hermes.desy.de/CODES/....
• Images:
  • If you have images to include in the documentation pages (screen caps, plots, etc) just upload them directly to the wiki. Use the Upload file button near the bottom of the wiki pages' left column. The name you give to your file has to be unique, but don't worry: if someone else has already uploaded a file of the same name you will be warned and asked to choose a different name. Accidental overwrites are also pretty safe, as wiki keeps history of every change, old versions are always available for rollback.

MediaWiki editing

MediaWiki has its own formatting and linking tags, which are beautifully summarized in the 1-page WikiMedia quickref. The left column of this page contains a link to this guide. However, MediaWiki also understands normal HTML, which is very cool. :-) The only exception is links. There you must use the Wiki syntax: single square brackets for external links, and double square brackets for links to other pages in our wiki.

Do not use discussion pages

All comments concerning the pages should be put directly on the page, using the flags that are explained above. The discussion pages have been disabled to avoid confusion.

Wiki care guide

The wiki administrator should refer to the Wiki Care Guide for tip on how to maintain the wiki