Wiki editing policy

From neicext
Jump to navigation Jump to search

This page describes philosophies, rules and style guidelines for smooth collaborative utilization of the NeIC wikis as the de-facto core collaboration tool in NeIC.

This policy was instated on 2016-02-16 by NeIC XT based on an analysis of NeIC web presences by Joel Hedlund, and after review by NeIC XXT.

This document was initiated using a verbatim copy of the report text (cf minutes [1]), and will be revised for readability, however the principles and recommendations described herein are to be regarded as instated policy.

The processes described herein are underpinned by NeIC policies on openness, information, shared personnel information, and working routines.

See also:

Rationale

In 2020, NeIC will be a global role model for cross-border distributed and sustainable e-infrastructure services.
--NeIC Vision in 2016-2020 Strategy

What does that mean?

Well for example, we want someone halfway across the globe to be able to to say:

- Hey, did you hear someone managed to do X?
- No? Did they really?
- Yeah, it was in a NeIC report!
- Oh wow, that's great!

To get there, we need to be The Best at communication.

Guidelines

  1. Openness policy:
    • Read the Openness policy. Seriously.
      When in doubt, go public. Strive to find good ways to do this.
      The external wiki is the place for the most up-to-date information on NeIC activities.
      The internal wiki is the place for working materials in NeIC activities (please remember to mark them as drafts not for dissemination).
    • Always push to be more open!
    • First question should always be "Can I publish this?"
  2. Don't duplicate info!
    • Because duplicated info rots.
    • Solution: See above.
  3. Use the tools!
    • We have tools to make your life easier while increasing transparency at the same time. Use them!
    • Cf #Contact info api below.
    • Also see above.
  4. What can you delete?
    • Wrong info is worse than no info.
    • Delete the wrong info: Now.
    • Add correct info: later, when you have it.
    • Words can be a barrier to communication.
    • The less you need to read, the more you can learn in the same amount of time.
    • Aim to have a sleek structure; not a lot of text, easy to understand, less info to maintain.
    • You should ask yourself:
      • "Can I say this with structure instead of words?"
      • "Can I make this shorter, clearer, more maintainable, and more understandable, at the same time?"
  5. Choose your tools!
    • Read the Working routines policy. Seriously. Summary: Use Your Head.
    • If your team would rather work in another tool or format, then it is ok to put content elsewhere and link it.
    • As long as it's clearly linked and easily found: that's what matters.
  6. Roadmaps are good!
    • Put important deadlines on display so that people see them, internally and externally.
    • Try to link this to "milestones", or "outcome statements". Makes the director happy.
  7. Use categories!
    • Categorization makes content findable, even if the page linking the content disappears.
  8. Continuous improvement!
    • You are the star. You make this work. You make this right.
    • No one else will try harder than you do.
    • Make it a little better each time you touch it.
  9. The statement that "10% covered and 90% understood is better than 90% covered and 10% understood" is bullshit.
    • That's "Propaganda".
    • We don't do Propaganda, we do Truth.
    • Give people Facts, and the means to understand them.
    • Make it as simple as possible, but no simpler than that! Then link to docs instead.
    • Don't feed our valued clients bad info just because you think little of their ability to understand facts! They may surprise, or learn!

Rules

Use ISO dates YYYY-MM-DD

Rules:

DO use ISO dates YYYY-MM-DD
DO NOT use any other ordering of Y, M and D. (Unless you are spelling it out in running text like "January 16 2018".)
DO change non-ISO dates to correct ISO dates.
GOOD: 1978-02-18, 2020-12-10.
BAD: 1978-18-02, 2020-10-12 (aaaaaaaaah!!!!!), 101220, 180278, 1978/02/18, 2020/12/10, 12.10, 10/12, 12/10, ...
Please avoid: YYMMDD, 780218, 201210.

Rationale:

  • Mixing date formats will cause confusion everywhere, not just on your page.
  • We have many numbers with punctuation in them (board and other agenda items on the format "16-18-03").
  • The less confusion we can have on these matters, the better.

Use lowercase in titles

Especially in page titles. But also in all other titles, as titles are linkable.

Rules:

The right way: DO use all lowercase in page titles, except:
proper nouns, like Joel, Linköping, Sweden.
first character in the first word (mediawiki forces this to happen).
well-known exceptions with well-established capitalizations, like NeIC, SNIC, CodeRefinery.
DO rename ("Move") pages with mis-capitalized titles so they get correct capitalization, and DO leave a redirect behind.
GOOD: "Best practices for big data handling in biobanking workshop 2015"
BAD: "Best Practices for Big Data Handling in Biobanking Workshop 2015"
BAD: "Best practices for Big data Handling in Biobanking Workshop 2015"
BAD: "Best Practices for big data Handling in Biobanking workshop 2015"
BAD: "Best practices for Big Data Handling in biobanking Workshop 2015"
BAD: "Best Practices for Big Data handling in Biobanking Workshop 2015"
BAD: "Best Practices for Big Data handling in Biobanking workshop 2015"
GOOD: "Tryggve steering group meetings 2015"
BAD: "Tryggve Steering Group Meetings 2015"
BAD: "Tryggve Steering Group meetings 2015"
GOOD: "Tryggve people and partners"
BAD: "Tryggve People and Partners"

Rationale:

  • Mixing capitalization styles is really toxic for a wiki and causes confusion everywhere, not just on your page.
  • Getting this wrong will make the wiki harder to work with. Since the wiki is our de facto core collaboration tool, we cannot afford that.
  • Wiki page titles are case-sensitive, so "Conference program" and "Conference Program" are treated different. Linking a page requires using the same spelling (and capitalization) as the page title that you want to link to, or the link does not work: it becomes red.
  • "Correct" title capitalization in English is a non-trivial subject, subject to subjective interpretation.
  • Rules like "Capitalize the first, last and any important words in a title" do not really help for getting a page link right.
  • Here are some rules that are good in general, but useless for a wiki: http://grammar.yourdictionary.com/capitalization/rules-for-capitalization-in-titles.html
  • "Getting this right" means using a super simple rule that requires zero thought to remember or carry out (cf "The right way" above).
  • Getting this wrong makes it so that everyone has to keep track of what page was originally authored by what person and "What their favorite Capitalization paTtern" is, or you can't link anything without having to first search for it.
  • NeIC is multicultural.
    • Different cultures have different capitalization habits. Say the page title text is "Napoleon did nothing wrong".
    • Germans want to capitalize Every Noun in Existence, regardless of what Language they type in, and so type "Napoleon did Nothing wrong".
    • Americans want to Capitalize key Words and the last Word. So they type "Napoleon did nothing Wrong".
    • Some People Want To Capitalize Everything, and so type "NAPOLEON DID NOTHING WRONG".
    • So here, in this wiki, different cultures will just have to accept "the simple rule" above so we can get work done. End of discussion.

Example:

  • Was it "Pool competencies", like it is in the internal wiki? Or "Pool competencies", like "Strengthen stakeholder dialogue" spells it?
  • No, *redlink* it isn't. Hit search, type it out, click page, copy text, go back, click edit, find wrong link, paste correct text, click save, repeat for next broken link.
  • All that can be avoided "With consistent capitalization".

Use lowercase in text

Rules:

The right way: DO use all lowercase in running text, except:
proper nouns, like Joel, Linköping, Sweden.
first character in the first word of the sentence.
well-known exceptions with well-established capitalizations, like NeIC, SNIC, CodeRefinery.
DO NOT: unnecessarily capitalize key words or concepts in running text.
DO edit pages with mis-capitalized words so they get correct capitalization.
GOOD: "The deliverables were approved by the Tryggve project steering group."
BAD: "The Deliverables were Approved by the Tryggve Project Steering Group."
BAD: "The deliverables were Approved by the Tryggve project steering group."
BAD: "The deliverables were approved by the Tryggve project Steering Group."
BAD: "The Deliverables were Approved by the Tryggve project steering group."

Rationale:

  • Some feel that text is more easy to read if Key Concepts are Capitalized.
  • This is fine and adds value within the agreed confines and defined limit of one publication.
  • But not on a multi-author, multi-project, multi-document platform such as the NeIC wiki.
  • NeIC is multi-team, multi-author, multi-perspective, multi-key-concept.
  • Everyone has a Different notion of What a key concept Is.
  • This cannot be agreed on usefully cross-teams nor cross-time, nor cross-perspective.
  • A concept that is core to your document may be irrelevant in a document that you link to.
  • Moving cross-document, the reader no longer has any use of The Capitalizations You Imposed in Your Document, but which now rather get in the way of understanding the next document correctly.
  • Used inconsistently, The capitalization Now Obscures clarity.
  • So here, in this wiki, different teams and cultures will just have to accept "the simple rule" so that our text can look consistent cross-team, cross-document, cross-perspective, and cross-time.

Avoid punctuation in page titles

Punctuation makes pages hard to link. See also #Use lowercase in titles.

Rules:

DO NOT use punctuation in page titles if you can avoid it.
DO NOT avoid it if doing so makes it harder to read.
GOOD: "Tryggve steering group meeting 2014-10-01"
BAD: "Tryggve-steering-group:meeting/2014-10-01"
GOOD: "Strategy 2016-2020"
BAD: "Strategy 2016 to 2020"

Rationale:

  • Having to remember whether it was
    BAD: "Tryggve / steering group: meeting 2014-10-01" or
    BAD: "Tryggve/steering group: meeting 2014-10-01" or
    BAD: "Tryggve:steering group meeting/2014-10-01" or
    BAD: "Tryggve - steering group - meeting / 2014-10-01"
    adds complexity without much added utility, and neither is as readable as:
    GOOD: "Tryggve steering group meeting 2014-10-01"
  • Page titles are not filename paths. Slashes have no special significance for normal wikipages.

Avoid prefixing page titles with NeIC

Rules:

DO NOT start your page title with NeIC, if you can avoid it.
GOOD: "XT meetings 2017"
BAD: "NeIC-XT meetings 2017"
GOOD: "Strategy 2016-2020"
BAD: "NeIC strategy 2016-2020"
GOOD: "Training policy"
BAD: "NeIC training policy"

Rationale:

  • This is the NeIC wiki.
  • Expectation: All pages are about NeIC, unless otherwise is explicitly specified.
    • Example: if there is a page called "Strategy" on our wiki, whose strategy do you think it is? Does it need to say "NeIC Strategy" in order for you to be able to understand whose strategy it is?
  • Done right: Only very few pages need such specification in the title.
  • In a wiki you link pages by typing out their names.
  • Done right: We need not type a lot of "NeIC" in order to be able to link pages.
  • If we do this wrong, and start prefixing many pages with "NeIC", then casual visitors are likely to wonder why "Why does this page not say NeIC? What's the difference between this and the other page that does say NeIC? Is this one not about NeIC?"
  • This also applies to links in text. If 50% of links in text refer to "NeIC X" and "NeIC Y" and suddenly there's a "Z", people will be confused and might think that the text does not actually refer to NeIC, but to some other organization.
  • Done wrong: we need to prefix everything with NeIC.
  • Done wrong: we have to type "NeIC" into the wiki 200 times per hour, rather than 20.
  • This is silly and inutile and will give people carpal tunnel syndrome.

Use descriptive and readable page titles

Rules:

BAD: "SteeringGroupMeeting 20170111"
GOOD: "Tryggve steering group meeting 2017-01-11"

Use specific page titles

BAD: "Meeting with DIRAC"
Good: "E3DS meeting with DIRAC 2016-09-03"

Rationale:

  • Someone else might want to meet with DIRAC in the future, and will not like to have their meeting confused with yours.

No syntax errors

Rules:

DO use syntactically correct mediawiki markup.
DO NOT leave square brackets and other cruft littering the page for no reason.
DO look at what you just published! If it looks like some crazy stuff, then DO fix it!
DO NOT leave any crazy broken gibberish behind to confuse our clients, partners, funders, users...

Fix broken links

Rules:

DO fix broken (red) links.

Avoid long lists of attachments on pages

  • Please refrain from having (possibly long) list of "attachments" at the bottom of the page.
  • They are rarely informative or useful.
  • You can upload files by clicking "Upload file" in the sidebar instead.
  • You don't have to use the "Attach file" button on top (which is what makes the useless "Attachments" list of (usually non-descriptive) file names at the bottom).

Avoid long lists of page links

  • Please refrain from using long lists of links to pages.
  • Put them in a category instead and link that. Less manual maintenance, less broken links.

Contact info api

We have tools to make your life easier and increasing transparency at the same time! Use them!

Use this instead of manually updating contact info tables (in several places)!

Examples:

Howto:

This also has other benefits.

Up-to-date contact info, with additional internal info, on the internal wiki:

Up-to-date staffing info (which you will have to report to board quarterly anyway), on the internal wiki:

Links

Retrieved from "https://wiki.neic.no/w/ext/index.php?title=Wiki_editing_policy&oldid=7256"