Streamlining documentation pages

[nschneid]

#7198 made the basic additions for the author transition. In general, a full review of documentation pages seems like a good idea to remove redundancies and present information more clearly.

Specific ideas:

• FAQ: "How can I submit corrections to papers?" itemizes different types of corrections. It can probably just link to the corrections page.
• For author page corrections, do we want to keep the splitting/merging perspective currently on the corrections page and related pages? Or move to a framing that emphasizes verification + supplying ORCID iDs at the paper level?
• We have a new page on verification and a new page on names. Relatedly, there is "what users should know" content and there is technical "how this works under the hood" content. I am not sure the current organization is the most straightforward. We give info on how to verify an author, but what this means is motivated in terms of database architecture—it's not framed as solving a problem that the user sees (other than an icon being the wrong color).

[weissenh]

Thanks for creating this issue!
Definitely seconding the point of making sure it is described such that the users will understand what's in for them: how they can best benefit from this new author representation, and understand what will happen with newly ingested papers co-authored by them or their namesakes with or without ORCID information.

If I find time in the future (strong emphasis on if) I might work on the points I stumbled over and commented on in the PR. Here are my rough notes for my future self on potential changes:

• on info/orcid
  • done wording "please consider the following tips to help match your papers to your Anthology page" got me (and Marcel) confused when comparing to points directly below this. (for regular automatic comparison? or for reviewing author page requests? one point more to ensure permanent access)
  • optionally: explicitly state each person should have one, not multiple, ORCID iDs. (orcid.org has documentation on how to link existing ones, they are meant as identifiers, our logic doesn't support persons with multiple ORCID iDs)
  • optionally: add more info on how to add ORCID to Softconf, link to OpenReview documentation? (necessary steps already mentioned as a comment in linked PR)
• on info/verification
  • optionally mention non-GitHub way to submit author page corrections, cf general corrections info page
  • phrasing below verifying an author: verify yourself vs others, GitHub - next sentence anthology page?. Call it button not link? Maybe elaborate on points more (e.g. carefully and completely read through and fill out the form: easier/faster to review)
• decide how much weight we should put on emphasizing metadata corrections and how they relate to author pages (e.g. "merging"/"splitting" via metadata corrections)
• compare requested info in form with how we describe on info pages what is necessary for author page requests: is it in line or important details missing?

[weissenh]

Btw we might also want to review the wiki pages: there is a page on name variants (which might be linked to from other pages, the title probably hints more to the old yaml than just a list of variants of a name) and the author page plan. The wiki home/overview page should correctly link to updated information too. The page on how to process author page requests could be simplified too, especially if new tooling becomes available (using python library/GUI rather than fiddling with data?)

[nschneid]

Yes, I'm wondering if we should explicitly have a set of pages of technical documentation and a different set of pages that are very user-focused ("what is the Anthology for?, how can I find stuff?, how can I correct errors?").

[mbollmann]

Noting that there is some natural overlap between "technical documentation" in general and documentation that’s already in the Python library, which e.g. explains how Anthology IDs work or what the difference between names, persons, and author tags on papers is.

[davidweichiang]

Very exciting to see the switch to the new system! I want to second the need for clear step-by-step instructions for users to get verified. I am not sure what those steps are (and am thankful that it all just worked magically for me). I would think that these instructions would appear on the page linked to by the question mark.

[nschneid]

Right, that is the intention...is the link not working on some pages?

[davidweichiang]

I see, yes, it's working fine, but I wasn't reading carefully and missed the list at the bottom. I'll make a pull request to suggest some changes to this page. Thanks!

[davidweichiang]

In my opinion, there's some nerdview on this page (info/verification). Many users will only be interested in fixing their author page, and not interested in any details of how the system works. In addition, the more detailed (but important) instructions are on a different page (info/orcid). Before I make edits, do you think it would be better to merge info/verification and info/orcid into a single page with multiple sections (e.g., what is verified/unverified, how do I get verified, and how does it work under the hood)?

[nschneid]

There are incoming links from other pages that would have to be considered, and I want to take a more careful global look at all the docs before reorganizing what the pages are.

What about rearranging the organization of info/verification to put the step-by-step part first and technical details below?

[davidweichiang]

I would definitely favor putting the step-by-step section above the technical details in info/verification. But currently some of the steps are on info/orcid. I feel like all the steps should be in one place.

[nschneid]

We are getting plenty of verification requests, so it seems that people are able to figure it out. But there is definitely room for improvement—if you want to get things moving with a PR, feel free. :)