Documentation week wishlist

The page needs work:

  • The 'summary' currently points to resources in the existing FAQ, so that needs to be changed.
  • We need a summary that gives a good overview, and explains how things (e.g. Kerberos authentication; AFS; etc.) fit together. For example: why might I want to install just Kerberos, but not AFS?
  • 'Using ssh' refers to Windows and MacOS/OSX only, not Linux. Seems an odd omission.
  • 'Using ssh' should refer to the use of ssh keys and warn why, for our systems (in particular, filestore) they probably won't work as the users might hope.
  • Configuration information for all this stuff should also be provided for cygwin: it's (probably?) a common way for users who use Windows machines at home to get remote access.
  • The general related point is: for which platforms/OSes are we providing documentation? We should make that selection explicit somewhere, and then we should make sure that it's consistently addressed across all relevant areas of our documentation.
  • Bottom line: put yourself in the position of someone who is intelligent, but who has never heard of (or used) either Kerberos or AFS, and who would now like to be able to use our systems remotely.
-- idurkacz

  • Could we expand to say something a bit more than "hi".
  • We should revise and expand on what facilities (school and university wide) are available for numerical computing. Where possible we should push people towards opensource solutions.
  • We should properly document the requested software queue and give users some idea of what software we are willing to install and how likely (and quickly) we are to install it.
  • We should build a list of stock replies to common questions and generate some Articles for RT.
-- iainr

The Documentation queue contains some longstanding documentation wishlist items.

-- gdutton

Remote working / filestore:

  • iFile/Filedrawers: Fully document this service, how it can be used, and when and why it might be useful. Explain how it can be used, in conjunction with iFriend, to give external collaborators access to files held in our AFS filestore.
  • Explain what content is stored - and what isn't - in our AFS filestore. (I.e. with the particular implication of what is, and what isn't accessible via the iFile service.)

-- idurkacz

Help / orientation for new users:

-- idurkacz

Though these stray into policy, rather than just "docs".

  • Obtaining extra disk space. How and at what cost. Does it last "forever"?
  • Backups / mirrors - what do we offer, and at what cost.
  • Account/project data archival.

-- neilb

RT 60840: Incorrect man page for 'bash' on DICE systems

-- cc

There are many policies at that haven't been migrated.

-- ascobie

IT Procurement under Policies and Guidelines - I get "Access denied. You are not authorized to access this page." Also there is no quick topic link for purchasing, although there's a short paragraph on the software page.

-- joxley

Consistency of abbreviations etc:
The Network> OpenVPN menu in the left side-bar currently reads:

  • OpenVPN
    • openVPN for MacOS
    • openVPN for Windows
    • OpenVPN for Linux and *BSD
    • Authentication
    • Config Files
    • OpenVPN FAQ
I.e. it's a mixture of leading 'o' and 'O'. I haven't scrupulously read the docs themselves, but we should choose one form of capitalization and stick with it throughout. (If I could make the changes necessary here myself, I'd do so: but I don't know how to change the content of the side-bar.) The same general comment applies, of course, to all other material on our documentation site.

The 'Guidelines' page, its subsidiary content pages, and its associated left side-bar entry, all take a random approach to the capitalization of individual words (other than the leading word) within headings. I don't care what standard we adopt, but whatever it is, it should be applied consistently.

-- idurkacz

OpenVPN docs at need revised and updated to cover our 'supported' platforms.

-- idurkacz

'Handling data': The entire page currently appears to be stub entry. This needs populated or removed before go-live.

-- idurkacz


  • The FAQ entry 'How does pcounter work?' points to the 'Printing from DICE machines' page That page doesn't mention the term 'pcounter' at all, so that's a little confusing for a new user.
  • 'Printing from DICE machines' also contains the sentence 'Due to the high cost of printing, from September 2011 there will be a system of charging introduced ...' Why bother to say all that? Why not just say 'We charge for printing per page' or similar.
  • I note that, in their docs, IS refer to the print charging system as variously 'pCounter', 'PCounter' and 'Pcounter'. I suggest we pick one variant, and stick with it.
  • Why do we include a link to the 'CUPS online help page' on How does that help our users?
  • Presumably now needs a Windows 8 entry, (as will anything else which refers to Windows.)
  • Will it be clear to users whether or not the above link applies to self-managed Windows machines, rather than 'MDP' machines? Do we also need an 'MDP' entry under the 'Printing' menu?

-- idurkacz

The FAQ entry 'Where can I run compute-intensive jobs?' points to the 'Commodity and public servers' page, and the clear (but false) implication for a new user is that staff.ssh, student.ssh, staff.login and student.login can all be used for compute-intensive work.

In addition, on the same page:

  1. The 'purpose' field of both staff.login and student.login is currently blank.
  2. It's not made clear what is the difference between, (or the difference in the intended use of) staff.compute and staff.compute64 (particularly given that both aliases now resolve to 64-bit machines: vulcan and torridon respectively.)

-- idurkacz

The printing section doesn't list what printers we have, where they are located, the naming scheme and who can use them. There is no mention of the monthly printing reports.

-- ascobie (for A Solomon)

Instructions on how to download various useful software for MacOS - eg TeX -Live

-- ascobie (for A Solomon)

How to retrieve email from the mailbox that the University has provided, how to forward this address to another address, how to set up outgoing email (I think part of this is already provided as part of induction but it needs a bullet point summary as people don't seem to read it); how to request an email address of the form;

-- ascobie (for A Solomon)

Some simple HOWTOs ?

  • How do I host a conference?
  • What options do I have for storing my data?
  • What tools are there for managing my software?
  • How do I give my visitor wireless access?
  • How do I buy some equipment off my research grant ?
  • I have a new research topic/group/project
    • how do I create an internal project collaborative area (eg wiki)?
    • how do I create a web presence for my topic/group/project
    • how do I store group data?
    • what tools are there for collaborating on software development?
    • how can I provide access to external collaborators?

-- ascobie

Health and safety guidance? - regular breaks, screen height etc

-- ascobie

Not many services mention iFriend access

-- ascobie

No documentation for

  • LDAP (users may want to use for self-managed linux?)
  • iFile
  • InSpace
  • Institute in a box?
  • Lecture recording
  • NTP (for self managed)
  • Online lab exams?
  • Restoring of user files
  • Archiving of user files (we don't!)
  • Exam preparation ?
  • Backups for self-managed linux
  • Why you should use virtualisation
    • what is available

-- ascobie

Many of the links to corpora, at, are broken.

-- ascobie

  • The "how to set up kerberos and AFS for windows 7" instructions don't actually appear to cover AFS. (They're also a PDF, but with all those screenshots that may not be easy to avoid.)
  • 'Using the AFS client' needs an entry for Windows 8, and it needs info for distributions of Linux other than just Ubuntu. All info should be normal web pages, not PDFs. Again there needs to be an explanation of / motivation for the installation of these things, not just bald step-by-step descriptions of the process.
  • The Kerberos and AFS Windows 7 instructions need checked and, if necessary, updated. They shouldn't be just a PDF
  • The info currently at 'Using the AFS client' for Windows might not be correct: see

  • Do we really want how-log-web-page-access? It should perhaps just say "ask HoS first" and "ask for advice, but we'll check with HoS".

-- gdmr


  • Guidance on setting up a web presence
    • Facilities available
    • Legal obligations etc.


  • Revamp and update documentation, quick start guides etc for new service

-- cms

From RT documentation queue

  • Modernise [al]pine docs and add filter guidance
  • Advice to those with firewall holes to their machines (advice on securing)
  • Some advice on "screen" for FAQ - RT 55573
  • Fix defaultletter in Prometheus/Tools/Password - RT 55161 - correct location for Uni Computing Regs
  • sox behaviour changed under F13/Sl6 - FAQ? (too late?)
  • alsamixer documentation (RT 41985)
  • Documentation on using MySQL under DICE (RT 41132)

-- ascobie

  1. -> 'set up a Virtual Network Computer (VNC)' The latter needs porting to Drupal.

  2. 'Platforms': all of the following need serious attention:

-- idurkacz currently has a stub entry "Our backup strategy is described ...."

-- idurkacz

-- AlastairScobie - 30 Jan 2013

Topic revision: r24 - 19 Feb 2013 - 16:55:33 - IanDurkacz
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies