search

visualize-admin / visualization-tool

The tool for visualizing Swiss Open Government Data. Project ownership: Federal Office for the Environment FOEN
https://visualize.admin.ch
BSD 3-Clause "New" or "Revised" License
30 stars 3 forks source link

docs: Initialize developer docs #1428

Closed bprusinowski closed 5 months ago

bprusinowski commented 5 months ago

This PR is a proposition to introduce a new type of closer-to-the-code docs (developer docs). For rationale, see https://github.com/visualize-admin/visualization-tool/blob/docs/developer-docs/docs/home.md

Next steps, if accepted

vercel[bot] commented 5 months ago

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Comments Updated (UTC)
visualization-tool ✅ Ready (Inspect) Visit Preview 💬 Add feedback Mar 25, 2024 4:06pm
bprusinowski commented 5 months ago

@ptbrowne I decided to open a PR for the proposal for developer docs as discussed offline; let me know what you think, we can also discuss next week 👍

bprusinowski commented 5 months ago

Thanks for reviewing @ptbrowne!

I think the original idea I had in mind was to rely on smaller files linked together by [[xyz]] tags, which allows you to quickly jump between files and having them open in several tabs, instead of scrolling back and forth in larger documents.

My slight concern with larger documents with table of contents would be more maintenance needed to keep the TOC in sync with content, as I didn't find a way to auto-generate it, like in Notion (there as some Obsidian plugins, but still you'd need to install and run when contents changes). On the other hand, I also see the issue with "in which file did I put this", but maybe if we link the things properly, that problem would not materialize badly 😅

I'll merge the PR in its current state, and maybe we can see how they work, and if we find this valuable, and adjust as needed 🙏