Wikidata:Requests for comment/Property documentation redux
An editor has requested the community to provide input on "Property documentation redux" via the Requests for comment (RFC) process. This is the discussion page regarding the issue.
If you have an opinion regarding this issue, feel free to comment below. Thank you! |
THIS RFC IS CLOSED. Please do NOT vote nor add comments.
- The following discussion is closed. Please do not modify it. Subsequent comments should be made in a new section. A summary of the conclusions reached follows.
- Stale. Being developed by the development team (in theory) through allowing statements on properties. John F. Lewis (talk) 15:31, 14 May 2014 (UTC)[reply]
I would like to re-open Wikidata:Requests_for_comment/Place_of_the_property_documentation, for these reasons:
- I think this issue is rather urgent. @Nightwish62: did a much better job than I could of describing the need for good property documentation. As a newbie to Wikidata, I can tell you that that's a huge barrier. The fact that properties are so inscrutable is a big reason I haven't tried to edit more data items so far.
- That RfC proposed two separate ways that documentation could be added, and suggested that one or the other be chosen. I would like to propose that both be implemented. I agree that "statements on property pages" are crucial, for hinting, affordances, and validation can be automated, but I think it's also really important that it be possible to include human-readable documentation on properties. Especially for newbies, lists of statements are very intimidating, and just do not serve as "documentation". Also, there's lots of information that can't be included in a statement; for example, step-by-step instructions on how to determine an GeneReviews identifier from the name of a disease.
I'd like to propose that the template/doc automatic transclusion mechanism be implemented as soon as possible for property pages. So, if, for example, Property:P31/doc exists, that it is transcluded into the property page itself. Klortho (talk) 06:32, 23 December 2013 (UTC)[reply]
- Support I am learning Wikidata myself and I do not fully understand the implications of this proposal, but it seems to me that this proposal calls for something reasonable and noncontroversial which already has support. Is this feature not in place only for lack of developer time? There is no reason why this kind of information would not be connected and no counterargument to doing this, right? Blue Rasberry (talk) 02:40, 24 December 2013 (UTC)[reply]
- Comment This is already on the development teams list. A new RfC is really just a waste of time as there have been around 4-5 discussions over this in the past. John F. Lewis (talk) 00:14, 25 December 2013 (UTC)[reply]
- I think this is inappropriate. The previous RfC close should be obeyed, not defied.--Jasper Deng (talk) 00:51, 25 December 2013 (UTC)[reply]
- Why inappropriate? This is not "defying" the previous RfC. As I stated, that RfC phrased the proposal in either/or terms. So this is really a new proposal (notwithstanding that I wrote "re-open" above), because I am suggesting that there's no reason that the two ideas need be mutually exclusive. From the discussions on that RfC, it doesn't appear to me that that was considered. Where else would you have me bring up this idea?
- John, I did some searching before I opened this, and couldn't find anything other than the prior RfC on: the Template:Property documentation talk page, the mailing lists, project chat, other RfCs, or mediawiki wikibase pages. Maybe I missed them. I don't want to waste anybody's time, but I hope you'd be willing to admit that sometimes it's not easy finding the discussions you're interested in. Please give me some links to those other discussions, so I can find out what's in the works. Thanks! Klortho (talk) 08:46, 25 December 2013 (UTC)[reply]
- I do admit searching and finding things here is sometimes complex. I'll put together a full list of links with discussions latert. John F. Lewis (talk) 14:03, 25 December 2013 (UTC)[reply]
- @John F. Lewis:, you shut down discussion of this issue, which I think is an important one for usability, so I really would like to find out what is in the works, if it's not too much trouble.
- Support Filceolaire (talk) 17:26, 11 January 2014 (UTC)[reply]
I have gotten very little/poor feedback above, so I want to describe this proposal more clearly, and give examples. There is nothing new here -- I just want to make sure that what I am suggesting is very clear.
I propose that there be an automatic transclusion mechanism for property documentation, which works the same way that template documentation does. That is, if there exists a page such as, for example, Doc:P1055, that it be automatically transcluded into the main property page, Property:P1055. I think this could be done in an unobtrusive way, perhaps in an expand/collapse block immediately under the title, which is collapsed by default.
This would be analogous to the way that, for example w:Template:Infobox_disease/doc is transcluded into w:Template:Infobox_disease.
Rationale:
This would allow human-written, and human-readable prose documentation, which I think is very important. I am pretty new here, but have been participating in a lot of discussions about properties, and what is immediately clear is that there is a lot of confusion about how these should be used, and no adequate mechanism for communicating decisions to later users/editors, once consensus has been reached.
In the earlier RfC, that this one stems from, it was decided to "Include property documentation by 'statements on property page'" (see also this enhancement task). While I fully support this, and definitely see the usefulness of machine-readable constraints, I see it as an orthogonal issue.
Sometimes there is no substitute for prose documentation. Having a separate wiki page where it could be written, and which would be unconstrained in length, and allow multiple sections, would be very valuable. For example, one could give details about use cases, with examples, and links to other sources of information. Just look at (any of the subsections) of the Infobox_disease documentation for examples of what I mean.
I proposed the namespace "Doc" above, because having the page at 'Property:P1055/doc' (mirroring the way it's done with templates) would not work, since that would be interpreted as an item page. 'Property_doc:' might be a better choice, I'm not sure.
I have to say I'm a little vexed by the comments above that this is inappropriate, or that I'm wasting people's time, without any justification. Please just vote "oppose" if you don't like the idea. But it seems clear to me that this particular proposal has not been properly vetted. In the previous RfC, the only "oppose" votes for this proposal were by folks who didn't understand it. Pinging the people who voted on that RfC: @Nightwish62:, @Snipre:, @Doostdar:, @Michiel1972:, @Thieol:, @4th-otaku:, @Tpt:, @GZWDer:, @Pigsonthewing:, @Pyfisch:.
- I'm not sure it's a good idea to add a new namespace, that will become redundant the very moment the developers have solved the issue with the earlier RfC. But it can still be solved, by creating pages like Template:Property documentation/P1234. -- Lavallen (talk) 19:37, 11 January 2014 (UTC)[reply]
- Comment There was discussions with development team about property metainformation month or two ago. I think it is better to investigate its planes before creating some new documentation mechanism. This can save us from double work. — Ivan A. Krestinin (talk) 19:42, 11 January 2014 (UTC)[reply]
- That's basically what John F. Lewis said above, and I asked on the email list, and got a pointer to this discussion on Property Metadata, which seems to have resulted in (or, at least, be related to) this enhancement task. Sorry, I should have mentioned that above. So, basically, the way I read those is that they are about supporting statements on properties, not about human-readable documentation. Klortho (talk) 19:48, 11 January 2014 (UTC)[reply]
- Do you think statements in the Q-namespace are hard to read for humans? -- Lavallen (talk) 19:53, 11 January 2014 (UTC)[reply]
- For most (non-technically-inclined) humans, yes, certainly. But that's not the main issue. As I attempted to describe, statements are not a substitute for some kinds of human-readable documentation. Klortho (talk) 20:22, 11 January 2014 (UTC)[reply]
- Do you think statements in the Q-namespace are hard to read for humans? -- Lavallen (talk) 19:53, 11 January 2014 (UTC)[reply]
- That's basically what John F. Lewis said above, and I asked on the email list, and got a pointer to this discussion on Property Metadata, which seems to have resulted in (or, at least, be related to) this enhancement task. Sorry, I should have mentioned that above. So, basically, the way I read those is that they are about supporting statements on properties, not about human-readable documentation. Klortho (talk) 19:48, 11 January 2014 (UTC)[reply]
- Comment: Klortho, see Property:P492 and Property_talk:P492/footer. It should be possible to use transcluded 'footer' pages as a mechanism for what you're trying to achieve. (Kudos go to Multichill for developing support for 'footer' transclusion.) We could include both prose and enhanced property parameters on that page via the Statement template. (Of course, statements about properties wouldn't be tied into Wikibase, but it would be a good desire path to hint to developers that we want them.) Emw (talk) 19:58, 11 January 2014 (UTC)[reply]
- Yes, that seems very close. Does that mean you support this idea? Where was this discussed? Is this just a proof-of-concept, or is it something official? I am not crazy about "footer" for the name, because it conflates a presentation concept with its intended purpose. Klortho (talk) 20:31, 11 January 2014 (UTC)[reply]
- Klortho, I'm inclined to use 'footer' in a manner closer to http://dbpedia.org/ontology/capital than en:Template:Infobox_disease/doc. In other words, I think the 'Property' namespace and its pages should prioritize statements about a property -- like the Q namespace does for items. This would indicate that we desire to treat properties like they are in OWL, defining properties for properties like rdfs:domain, etc. It would entail creating new properties 'domain', 'range', 'one of', etc. and applying them only to resources in the Property namespace via soemthing like the Statement template and not applying those properties in the Q namespace.
- The extended prose documentation you cite as being needed for P21 has traditionally been handled at the top of the property's talk page. I agree that this documentation needs to be prominent, but I lean toward not putting it on the property page itself. I think the very top of the property talk page might be more appropriate. Make it the first thing the user sees upon going to the property talk page. Move the 'one of', 'single value' etc. completely off the talk page and to the property page -- since those templates are really making direct, semantic statements about the property. Emw (talk) 01:19, 13 January 2014 (UTC)[reply]
- Yes, that seems very close. Does that mean you support this idea? Where was this discussed? Is this just a proof-of-concept, or is it something official? I am not crazy about "footer" for the name, because it conflates a presentation concept with its intended purpose. Klortho (talk) 20:31, 11 January 2014 (UTC)[reply]
- Comment Hey, I would like to ask you if you might explain a bit further what specific information should be included into the documentation and why this cannot be handled by the features we have or are going to have (statements + description). If the problem only affects the display of this information we can create a gadget for that purpose but if it concerns the type of information that is provided we need another solution. Kind regards, -- Bene* talk 14:14, 12 January 2014 (UTC)[reply]
- Here are two examples of the kinds of documentation I'd like to see, that wouldn't be possible with statements+descriptions:
- Lists of examples illustrating "best practices". Look at this lengthy discussion on the naming and usage of sex or gender (P21). It's very controversial, and, since it's an extremely common property, important. Participants expended (a combined) tens, if not hundreds, of hours on the discussion, and the results (which are still a bit up in the air, I think) are non-intuitive. So, as I suggested here, it would be really nice to document the outcomes as a set of examples with best practices recommendations. There are lots of complexities and nuances, that, in my opinion, would be impossible to capture in anything but prose.
- For authority properties, it would be nice to provide descriptions of the identifiers, and/or instructions for how an identifier could be found on the external site. Take a look at w:Template:Infobox_disease/doc#Usage_summary, and the documentation there about the ICD identifiers. It is very nice and useful. I suppose that when this data moves to wikidata, a lot of this will be done by bots, but I think there will always be a need for humans to curate this stuff, and where else is this kind of documentation going to live?
- Klortho (talk) 17:58, 12 January 2014 (UTC)[reply]
- Here are two examples of the kinds of documentation I'd like to see, that wouldn't be possible with statements+descriptions: