Documentation week TODO

General actions

  • Check your unit's existing content for validity and, when happy, set the last reviewed date for each checked page.
  • Trawl through the DICE wiki (and www.dice) for your unit's docs to transfer across to new site. Delete or mark as unmaintained those user docs that you don't transfer.

Specific actions

Your unit should start work on the allocated tasks marked as H priority. Once those are complete, pick any M priority item that you feel capable of authoring and announce to COs that you are volunteering to tackle that item. Mark up the table to indicate that the item is being worked on.

Area Priority Unit What
Remote-working H Services The 'summary' currently points to resources in the existing FAQ. The new site has nothing on "how to access your account from outside Informatics". One needs to be created and filled with good advice, then linked to from the Remote Working page.
Remote-working H services 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?
Remote-working H MPU 'Using ssh' refers to Windows and MacOS/OSX only, not Linux. Seems an odd omission.
Remote-working H MPU '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.
Remote working     The "support page" link in the Windows bit of "Using ssh" links to the old Support FAQ ("our existing FAQ"). It needs to link instead to somewhere on the new pages.
Remote working     'Reading Email' should no longer link to www.sms.ed.ac.uk. Presumably it should link to https://www.office365.ed.ac.uk/ or just to http://computing.help.inf.ed.ac.uk/mail
Remote-working L   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.
Remote working     Create and populate the /using-ssh-ios page.
Remote working     Create and populate the /using-ssh-android page.
Remote working     Document AFS and kerberos for iOS
Remote working     Document AFS and kerberos for Android
Remote working H services introduce some structure to the remote-working page
Remote working H ascobie VNC instructions need transferred to new system and checked
Platform support H HOC 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.
Platform support L   The Platforms menu needs an entry for iOS.
Platform support L   The Platforms menu needs an entry for Android.
help.inf M   Could we expand http://help.inf.ed.ac.uk to say something a bit more than "hi".
Numerical computing M iainr 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.
Software queue H RAT 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.
iFile H services 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.
iFile M services 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.)
New users H USU/HOC There are currently a few 'check this' and '???' entries in all of http://computing.help.inf.ed.ac.uk/new-academics, http://computing.help.inf.ed.ac.uk/new-admin-staff, http://computing.help.inf.ed.ac.uk/new-taught-students and http://computing.help.inf.ed.ac.uk/new-visitors.
New users H HOC/MPU New users will not know what the term 'DICE' means, or what the acronym expands to, but the term 'DICE' seems to be used with no prior explanation on, for example, the pages http://computing.help.inf.ed.ac.uk/platforms and http://computing.help.inf.ed.ac.uk/dice-platform. This needs fixing somehow.
New users L/M   The 'Introductory lecture on the DICE desktop' link on http://computing.help.inf.ed.ac.uk/dice-platform appears to point to a 2011 version and, in any case, points to a PDF file, which we don't want to do (do we?) - That was the most recent version, and the PDF is issued as a handout to the students. Converted from PDF and uploaded but needs tidied and updated for 12/13.

Has this really been done? The doc still seems to appear as a PDF in http://computing.help.inf.ed.ac.uk/dice-platform

Filespace/Backups policy M->H Services Obtaining extra disk space. How and at what cost. Does it last "forever"?
Filespace/Backups policy M->H Services Backups / mirrors - what do we offer, and at what cost.
Filespace/Backups policy M->H Services Account/project data archival.
bash H RAT http://computing.help.inf.ed.ac.uk/dice-bash
RT 60840: Incorrect man page for 'bash' on DICE systems
policies H HOC There are many policies at http://www.inf.ed.ac.uk/systems/policies/index.html that haven't been migrated.
policies H HOC 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.
Consistency of abbreviations L   The network OpenVPN menu is 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.
Consistency of abbreviations L   The 'Guidelines' page http://computing.help.inf.ed.ac.uk/guidelines, 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.
OpenVPN docs H infrastructure OpenVPN docs at http://computing.help/openvpn need revised and updated to cover our 'supported' platforms.
'Handling data': H HOC The entire page http://computing.help.inf.ed.ac.uk/handling-data currently appears to be stub entry. This needs populated or removed before go-live. - Will create a left menu Guides entry which will include the Handling Data (renamed to Storing Data) page - also web presence guide
Printing H services/USU The FAQ entry 'How does pcounter work?' points to the 'Printing from DICE machines' page http://computing.help.inf.ed.ac.uk/printing-dice-machines. That page doesn't mention the term 'pcounter' at all, so that's a little confusing for a new user.
Printing H services/USU '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.
Printing H services/USU 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.
Printing H services/USU Why do we include a link to the 'CUPS online help page' on http://computing.help/printing-dice-machines? How does that help our users?
Printing L services/USU Presumably http://computing.help.inf.ed.ac.uk/printing-windows now needs a Windows 8 entry, (as will anything else which refers to Windows.
Printing L services/USU 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?
Printing H services/USU 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.
Compute jobs H USU The FAQ entry 'Where can I run compute-intensive jobs?' points to the 'Commodity and public servers' page http://computing.help.inf.ed.ac.uk/public-servers, 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.
Compute jobs H USU In addition, on the same page:The 'purpose' field of both staff.login and student.login is currently blank. 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.)
Useful mac software M   Instructions on how to download various useful software for MacOS - eg TeX -Live
Email H USU 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 yourname@edREMOVE_THIS.ac.uk;
EMail     The mail page should not simply link to "staffmail" and "studentmail" when a significant number of students use staffmail rather than Office 386.
Howto M How do I host a conference?
Howto M   What options do I have for storing my data?
Howto M   What tools are there for managing my software?
Howto H USU How do I give my visitor wireless access?
Howto M   How do I buy some equipment off my research grant ?
Howto M   how do I create an internal project collaborative area (eg wiki)?
Howto M   how do I create a web presence for my topic/group/project
Howto M   how do I store group data?
Howto M   what tools are there for collaborating on software development?
Howto M   how can I provide access to my web/code/collab-area to external collaborators?
Health L   and safety guidance? - regular breaks, screen height etc
iFriend H infrastructure Create a table on iFriend page so can list services that support iFriend - early draft here, please fill in!
iFriend H ALL Add those services that support iFriend to above table, and note support in individual service docs
Missing docs M MPU DIYDICE
Missing docs L   LDAP (users may want to use for self-managed linux?)
Missing docs M RAT InSpace
Missing docs M RAT Projects database website
Missing docs M RAT Move self-managed matlab documentation from wiki
Missing docs M services Institute in a box?
Missing docs M infrastructure NTP (for self managed)
Missing docs M USU Restoring of user files
Missing docs M USU Exam preparation
Missing docs H services Backups for self-managed linux
Missing docs M RAT Why you should use virtualisation and what options are there
Corpora H USU Many of the links to corpora, at http://computing.help.inf.ed.ac.uk/corpora-list, are broken.
Windows AFS H services 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.)
Windows AFS L 'Using the AFS client' needs an entry for Windows 8, and it needs info for distributions of Linux other than just Ubuntu.
Windows AFS H services 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.
Windows AFS H services The Kerberos and AFS Windows 7 instructions need checked and, if necessary, updated - see https://rt4.inf.ed.ac.uk/Ticket/Display.html?id=60122
Web H services 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".
Web H services Guidance on setting up a web presence - facilities available and legal obligations etc
Git/Gerrit M   Revamp and update documentation, quick start guides etc for new service
Postgres M RAT Pull in user docs on postgres service from wiki
L Modernise [al]pine docs and add filter guidance RT 61442
H MPU Advice to those with firewall holes to their machines (advice on securing)
L   Some advice on "screen" for FAQ - RT 55573
M alsamixer documentation (RT 41985)
L/M Documentation on using MySQL under DICE (RT 41132)
L   The site could do with a favicon.
Filesystem M services rename Informatics Filesystem to Filesystems (in menu)
Filesystem H services MacOS docs for AFS
Filesystem H services Linux(Ubuntu) docs for AFS Integrate afs-debian-ubuntu as appropriate
Platforms H Chris self-managed-macos needs fleshed out
Platforms H Stephen self-managed-linux need fleshed out
Platforms H Alastair self-managed-windows need fleshed out
FAQ H   Does the question about installing AFS on Windows/Mac point to the right place ?
Software M RAT tidy up /software and reference IS available software pages
condor H   /condor has a link to a condor FAQ on www.inf but should this page not be removed?

General issues and Style Changes

Some things some of us reckon need a global fix (for content style) in site style/theme or admin interface. It's assumed that CSS changes can be done within the #main or .content-main DOM tree.

Element / Path Problem / Fix
code and tt text is too small
td { padding-left, padding-right } should be 4px / 0.4em or so
li { margin-bottom } needs to be larger
/admin/content/ could this show larger numbers of pages to make admin tasks simpler?
Taxonomy /taxonomy/term/ should be denied in robots.txt since all searched content should be accessed canonically.
Taxonomy We should have alternatives to the /taxonomy/term/<id> path as linking to taxonomy IDs is unhelpful for usability or persistence of content. Perhaps they can be aliased, like pages?
public-editable pages A few SelfManaged wiki pages used to be user-maintained. Simple moderation queue? "correction" link to support on each page? OR a different content type for user-contributed docs?
Sharing content between pages Does Drupal allow content to be transparently shared between pages at the sentence/paragraph/section level, perhaps using iframes? That would be useful where standard boilerplate needs to be included, or where two distinct pages have some common content
Content selected by 'Choose a topic -> GO' Can the order of the offered content be altered by the use of weights/hints or similar?
Mobile phones Consider using a responsive theme (eg Zen 7.x-5) to support mobile devices with tiny screens

-- AlastairScobie - 18 Feb 2013

Topic revision: r70 - 25 Mar 2013 - 17:08:34 - ChrisCooke
 
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