Oliver Bertuch (Apr 29 2026 at 20:27): Oliver Bertuch (Apr 29 2026 at 20:27):The development guide is getting out of hand. There is a very long list of pages and it's not even all about development of Dataverse. It's very hard to find things and people probably don't use it a lot, as some information is outdated and - you guessed it - hard to find.
Should we talk about creating a third level of TOC? Split up the pages into more sections like "Develop", "Integrations", "Release Processes" or something along these lines?
Philip Durbin π (Apr 29 2026 at 20:30):Yes, it's in dire need of a rewrite.
Philip Durbin π (Apr 29 2026 at 20:31):As a sanity check, we still like having it as a guide, right? Next to the other guides, I mean. You don't think we should split it off into its own separate world, do you? (It's ok if you do!)
Oliver Bertuch (Apr 30 2026 at 14:07):Here's a suggestion. WDYT?
Getting Started
- Introduction
- Development Environment -> "Setup Dev Environment (Docker)"
- Classic Dev Environment -> "Setup Dev Environment (Classic)"
- Windows Development -> "Setup Dev Environment (Windows)"
- Version Control -> "Contribute Your Code" + Page "Version Control Strategy" in Daily Dev
- Security -> "Security Issue Handling"
- Tools
Daily Development
- Coding Style
- Dependency Management
- Debugging
- SQL Upgrade Scripts
- Tips
Architecture and Design
- Consuming Configuration
- API Design
- Performance
- Geospatial Data
- Universal Numerical Fingerprint (UNF)
Testing and Quality
- Testing
- Troubleshooting
- Deployment -> "Deploying Review Environments"
Java Extensions and SPIs
- Search Services
- Metadata Export Formats
Integrations and APIs
- Dataset Migration API
- Dataset Semantic Metadata API
- Globus Transfer API
- Direct DataFile Upload/Replace API
- Make Data Count
- Auxiliary File Support
- Shibboleth, OAuth and OIDC
- Workflows
Release and Pipeline Engineering
- Making Library Releases
- Making Releases
Specialized Topics
- Font Custom
Delete:
Move To Installation Guide:
Oliver Bertuch (Apr 30 2026 at 14:08):What a third level can look like: we already have an example by @Philip Durbin π here: https://guides.dataverse.org/en/latest/container/running/index.html
Oliver Bertuch (Apr 30 2026 at 14:09):This would mostly only move things around plus a few renames. We can iterate from there, restructuring and adding more documentation.
Oliver Bertuch (Apr 30 2026 at 14:10):(And I can start adding docs for the fixture and other testing bits)
Philip Durbin π (Apr 30 2026 at 14:12):Apart from a few quibbles here and there, this looks fantastic! :tada:
Philip Durbin π (Apr 30 2026 at 14:12):Question though: Is the frontend in scope?
Philip Durbin π (Apr 30 2026 at 14:13):The frontend has its own dev guide here: https://github.com/IQSS/dataverse-frontend/blob/develop/DEVELOPER_GUIDE.md
Oliver Bertuch (Apr 30 2026 at 14:15):I'd say one day it should be included. I feel like the community appreciates we have 1 place we put all the docs. But it may not be necessary. We certainly would have enough places to put a nice introduction and crosslink to the detailed frontend guide. (e.g. in "Getting started")
Philip Durbin π (Apr 30 2026 at 14:21):I'd say the main guide should at least cover how to spin up the frontend. And possibly how to test from js-dataverse (that's why @Jan Range and I added this recipe). Because often you're creating or updating an API that will be used by these downstream projects.
Oliver Bertuch (Apr 30 2026 at 14:22):That sound reasonable. Should we lean more into the "backend" / "frontend" bit in the page titles?
Philip Durbin π (Apr 30 2026 at 14:23):Yeah, that's what I'm thinking.
Philip Durbin π (Apr 30 2026 at 14:23):To acknowledge the new reality.
Oliver Bertuch (Apr 30 2026 at 14:24):We could move the classic and windows pages to the "special topics" section, then there's plenty of space for a page "Backend Dev Environment" and "Frontend Dev Environment"
Philip Durbin π (Apr 30 2026 at 14:25):Obviously, we should see what @Ellen K @Cheng Shi and @Juan Pablo Tosca Villanueva think. Plus, @Eryk Kulikowski has hacked on the frontend. And @Vera Clemens has worked on a lot on js-dataverse. I just kicked off #ui-dev > dev guide reorg
Oliver Bertuch (Apr 30 2026 at 14:25):What other quibbles do you have?
Philip Durbin π (Apr 30 2026 at 14:27):Geospatial Data seems a bit out of place.
Philip Durbin π (Apr 30 2026 at 14:28):Lots of the APIs should move from the dev guide to the API guide.
Oliver Bertuch (Apr 30 2026 at 14:29):Geospatial Data: the page should probably be renamed. It talks about how Dataverse ingests shapefiles, so this kind of is about architecture. But I'm open to suggestions.
Philip Durbin π (Apr 30 2026 at 14:30):Also, and this is frontend-related, we should probably kill the Style Guide while we're at it. Or fold it under the new dev guide org for eventual killing, as part of JSF removal.
Oliver Bertuch (Apr 30 2026 at 14:30):I agree with moving API stuff to the API guide, but then I need to reorg the API guide, too :see_no_evil:
Philip Durbin π (Apr 30 2026 at 14:30):Sure, we can do it in chunks.
Oliver Bertuch (Apr 30 2026 at 14:31):Yeah, we could move the style guide to a subsection. Might be nice to call it "Legacy Frontend" or something. Or just put it under Specials, together with the Font Custom
Philip Durbin π (Apr 30 2026 at 14:31):@Oliver Bertuch if you really want, you can post something to https://groups.google.com/g/dataverse-dev . It would be the first message of 2026! :sweat_smile:
Oliver Bertuch (Apr 30 2026 at 14:33):I have a suspicion no one will give a dime... :see_no_evil: It's not a lot of people caring about docs :zany:
Philip Durbin π (Apr 30 2026 at 14:34):Yes. We do have @Dieuwertje Bloemen @Vaida PlankytΔ π¨ and @AmΓ©lie Fiocca though! The Documentation Working Group! :tada: Just wait until you see our poster! :smile:
Philip Durbin π (Apr 30 2026 at 14:51):Oh, and anything new we write should be in .md rather than .rst
Oliver Bertuch (Apr 30 2026 at 14:51):Do we have MyST etc in place?
Oliver Bertuch (Apr 30 2026 at 14:52):Oh I see it in requirements.txt
Oliver Bertuch (Apr 30 2026 at 14:54):Wait a second. I just found your QA bits. Should we think about re-integrating these things?
Philip Durbin π (Apr 30 2026 at 14:56):The QA Guide? What about it?
Oliver Bertuch (Apr 30 2026 at 14:57):I just suggested a section on "Testing and Quality". And there's a section on "Release and Pipeline Engineering". Shouldn't we try to re-add the QA engineering bits into this?
Oliver Bertuch (Apr 30 2026 at 14:58):Instead of having two guides this closely related?
Oliver Bertuch (Apr 30 2026 at 14:58):I understand it's mostly about the internal processes, but it's still about development.
Philip Durbin π (Apr 30 2026 at 14:59):Honestly, I don't think anyone would care if we delete the QA guide. I don't think anyone looks at it. It was sort of a failed experiment. But maybe we could fold some of its content into the dev guide, like you're saying. 
Oliver Bertuch (Apr 30 2026 at 14:59):And I totally get why you put it in a new guide altogether - the current state of the dev guide simply is too crowded and the QA pages would have made things worse
Oliver Bertuch (Apr 30 2026 at 14:59):I'd like that!
Oliver Bertuch (Apr 30 2026 at 15:01):I just started writing up my bits and bobs about the fixtures etc and am going to add that in a new folder "testing" in the "developers" folder. That way I'm unblocked and can create the content, no need to wait on a reorg. If I do this in a month, I've probably forgotten about it all :see_no_evil:
Philip Durbin π (Apr 30 2026 at 15:17):Sure, that sounds fine.
Vaida PlankytΔ π¨ (Apr 30 2026 at 16:09):ah, merging and simplifying documentation, one of the nicer things in life :sunglasses:
Philip Durbin π (Apr 30 2026 at 16:12):@Oliver Bertuch see! @Vaida PlankytΔ π¨ cares about docs! :heart: 
Oliver Bertuch (May 03 2026 at 20:35):Crazy idea: let's talk about this in Barcelona, maybe even do some hands on editing?
Philip Durbin π (May 04 2026 at 11:52):Sure! I could even bring it up during the doc working group meeting in Barcelona if you want: #docs > docs wg at DCM 2026 in Barcelona
Oliver Bertuch (May 04 2026 at 13:15):Yeah that's what I meant :sweat_smile:
Oliver Bertuch (May 04 2026 at 13:15):Sry should have been more specific...
Philip Durbin π (May 05 2026 at 00:00):Sure, I just added it to the agenda: https://docs.google.com/document/d/1dX8ktajVsRDk-MDF-yHWV0f4vIe8U3DWrSzIerVGlF8/edit?usp=sharing
Heads up to @Dieuwertje Bloemen, my partner in crime. :smile:
Last updated: May 30 2026 at 06:18 UTC