search

obi-ontology / obi

The Ontology for Biomedical Investigations
http://obi-ontology.org
Creative Commons Attribution 4.0 International
75 stars 25 forks source link

Wiki Guidelines #972

Open GullyAPCBurns opened 5 years ago

GullyAPCBurns commented 5 years ago

Hey Guys,

We've started piecing together documentation in the Wiki (which I think is a good thing, since there's a natural forcing function for us to keep the pages clean, updated, and readable). I'd like to start the ball rolling here about setting up some guidelines for how we write the documentation as well.

  1. Denote classes by using the box construct followed by a link to the short form of the URI in parantheses with a link that resolves to the underlying definition. In this way, we would denote Information Content Entity (IAO_0000030) as 
    `Information Content Entity` ([IAO_0000030](http://purl.obolibrary.org/obo/IAO_0000030))
  2. Use plenty of comments in the Markdown:
  3. Focus on short, readable english with lots of examples and diagrams.

Any other thoughts?

bpeters42 commented 5 years ago

Complete agreement on call 10/8. But it seems this should go on the wiki itself, rather than on the issue tracker?

jamesaoverton commented 5 years ago

Sorry that I couldn't make the call on Monday.

Agreed on (3). I don't quite understand (2) -- aren't HTML-style comments the preferred way in Markdown? Regarding (1), I think the term IRI is fine as a link without the ID in the text. I think Information Content Entity (IAO_0000030) is hard to read, and 'information content entity' is better:

['information content entity'](http://purl.obolibrary.org/obo/IAO_0000030)

The Wiki does most of what we want, but I think it would be better to put this content on the OBI website, which has its own repo: https://github.com/obi-ontology/obi-ontology.org We would be able to create documentation-specific issues and pull requests, and it would be a better place to store diagrams and images.

ddooley commented 5 years ago

2 is about beaming each other comments that only people who are editing the wiki document can see. They get filtered out of public display.

As for #1, I like the idea that the first instance of a term on a page appears as my long term name ([id which is clickable]) and then subsequent instances can just be my long term name , which is light on the eyes. 1st instance lets one see where the term is coming from without having to click on it.

jamesaoverton commented 5 years ago

I'm very comfortable with ontology IDs, but I can barely read the first paragraph of this page because of the formatting: https://github.com/obi-ontology/obi/wiki/Data-and-Values#introduction

When I want to know where a link goes, I move my mouse cursor over it and my browser shows me the URL. Maybe that's too 90's.

ddooley commented 5 years ago

ok, I get that; anyone else object to just linking the label? The ID's are more of a paper/publish need, not a wiki need.

bpeters42 commented 5 years ago

I agree with Damion and James.

On Thu, Oct 11, 2018 at 5:22 PM Damion Dooley notifications@github.com wrote:

ok, I get that; anyone else object to just linking the label? The ID's are more of a paper/publish need, not a wiki need.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/obi-ontology/obi/issues/972#issuecomment-429163938, or mute the thread https://github.com/notifications/unsubscribe-auth/ANN9Io0LHT0DvxoIlUxoCuUbzMXHu4quks5uj-C2gaJpZM4XLenS .

-- Bjoern Peters Professor La Jolla Institute for Allergy and Immunology 9420 Athena Circle La Jolla, CA 92037, USA Tel: 858/752-6914 Fax: 858/752-6987 http://www.liai.org/pages/faculty-peters