reosarevok: https://musicbrainz.org/doc/Work/Type would better follow the current structure of the documentation. It could be implemented by replacing on transclusion a placeholder in the wiki page with a React component (listing work types).
reosarevok
That would break as soon as we moved the docs to readthedocs or similar, but I guess it's otherwise doable
Wonder if we should have two fields, description and documentation or something
(schema change, but trivial otherwise, if useful)
lucifer
alastairp: thoughts on where the constants should go. i am thinking one common page of api explaining that we are https only, ratelimiting in future auth too. should constants go here or under individual api pages?
i think the constants we have currently deal with only single category so individual page should probably be fine.
alastairp
yeah, I was going to ask that
but maybe if we find enough items to put on a "how to use the API" page or section then that'd also be a good idea. rate limiting and auth are good items to put in such a section
reosarevok
We could then use that to show the descriptions for the currently selected types in a bubble or something like we do for other types
Right now we don't show anything on the release editor nor on "Add RG"
yvanzo
Would there be an issue with having large descriptions? (If they are displayed in editing forms for example?)
lucifer
👍
reosarevok
Well, if they are on the bubble and they close when tabbing away, probably not a huge issue either way
But I would still probably prefer just showing a basic one or two lines description, with a "see more" option for further documentation
alastairp
I think I may have opened a ticket or made a comment somewhere saying that we should unify all of the bits where we talk about authorization
but I can't find it
reosarevok
It's just that currently requires a schema change, AFAICT :)
lucifer
yes i think i assigned it to myself sometime ago
yvanzo
A foldable “see more” could be tagged into the description, just like the one in MeB blog posts.
reosarevok: yes “ a comment that we'd parse ” would do
reosarevok
So, store RG type descriptions there for now so that they're in the DB. Eventually show them as bubbles. Add a comment to collapse stuff if desired.
(maybe easier to do those display things once we have the editors all using React to avoid duplicating work)
goldenshimmer
I know Spotify pays a pittance, but if I bought all the music I want I'd probably be broke in a month and end up squished to death by a stack of CDs falling on me...
yvanzo
We can also keep the RG type wikidoc page for now, and just retrieve doc from the DB for other new doc pages such as work type.
(Whichever way is the simplest to follow.)
reosarevok
Sure, I'm also fine with that, but we'll want to add the descriptions to the DB anyway, that way they can also be translated and whatnot :)
lucifer
alastairp: another ques, where should pinned recordings go among the api categories in the doc?
social?
alastairp
I wonder if it's kind of related to feedback? they both deal with recordings
does that make sense? I'm not sure
lucifer
yeah, its kinda related. should it be called feeback and pinned recordings then?
alastairp
I don't think it's a good idea to just take the name of 2 APIs and call that a section :) what happens if we add another endpoint related to recordings
for now group them together and call it "Recordings", and then we can look at it and see if it makes sense
i have put the first under recordings, second under recommendations
outsidecontext
I can confirm the "temporary holes in Spotifys recently played API" theory
lucifer
thanks for looking into that and the detailed ticket!
outsidecontext
:)
alastairp
lucifer: that sounds like the correct split for these 2 APIs
reosarevok
yvanzo: copied those descriptions (with small modifications) to the attribute tables, at least :)
rdswift
reosarevok, yvanzo: Actually the Picard docs aren't hosted on readthedocs, but are just served from github gh-pages at this point.
As for users wanting to make changes to the docs, we're pretty flexible. Easiest is for them to attach the changes to a ticket and one of the maintainers creates the PR.
reosarevok
rdswift: so that means you have the rst files on github and then what happens? :)
rdswift
Yes, they are on the repo. There is a bunch of github actions to take care of testing and building the actual web site files.
We maintain a 'master' branch and a 'publish' branch. Changes are merged into 'master' and periodically we merge 'master' into 'publish'.
How do you decide how to organize the docs? What goes where and whatnot
I understand this is only user-facing docs, with the dev docs elsewher
e
I'm thinking for MB there should be two clearly different sets of docs, "how to use the site as a user" and "how to use the data as a data user", but not sure whether that'd mean two read the docs pages, or whether there's a good way to split the page in two like that
(since it seems more of a split than just the small headings in the Picard page)
rdswift
<reosarevok> How do you decide how to organize the docs? What goes where and whatnot? That's the role of the editor. Pretty much hit & miss right now. The docs just sort of "evolved" and I'm looking at possibly some restructuring.
It would have been nicer if I had a "master plan" in the beginning. ;-)
I think that it might make more sense in your case to plan on having two separate docs -- site use and data use.
reosarevok
So if we used your system that'd mean two repos?
rdswift
That would likely be the easiest, but it might be possible to do it in one. I'll have to give it some thought.
reosarevok
I mean, it might be easiest to have it in two repos also for translation, so that MB users can translate the docs for the site while data users can translate the other docs
Since I expect they'd not always be the sane people
... that too, but I meant same :D
rdswift
Possible to do it as two 'master' ('master_site' and 'master_data') branches and do some fancy github actions processing for the actual publishing.
reosarevok
bitmap, yvanzo ^ when you have some time it'd be fun to look into this
rdswift
I think it might be cleaner as separate repos though.
reosarevok
Yeah, me too
rdswift
The nice thing about weblate is that it can create a glossary for both and provide suggestions across repos.
reosarevok
Oh, neat, so we could have a shared glossary for both MB itself *and* the MB docs?
rdswift
Yup. The setup that outsidecontext maintains has a gloossary for Picard and another for Picard-docs and we can access both.
I would LOVE to have MB in there as well, for consistent use terminology. Right now the Picard Docs are a bit disjointed in that regard.
*use of terminology*
reosarevok
Well, if mayhem's conversation with the weblate people goes well, hopefully we will :)
!m mayhem & zas or increasing bus/tram/whatever factor!
BrainzBot
You're doing good work, mayhem & zas or increasing bus/tram/whatever factor!!
CatQuest
reducing? whatever
mayhem
increasing
Lotheric has quit
CatQuest
yea, since number s 2 now
mayhem
congrats and thank you, CatQuest.
I got boosted while I was in Cali/.
CatQuest
pfifer or modena?
I was actually given the option :o
mayhem
I was too and got moderna, since the first two were pfizer. wanted some cross training.
outsidecontext
rdswift: the MB glossary is also in the weblate and also assigned to Picard and picard-docs. But I just recently realized I'm about the only one seeing it :(
Because the project is not public. But that's something we can than get right once there is the MB weblate