Converging portaljs docs to datahub docs
rufuspollock
Converging portaljs docs to datahub docs
- Situation: we have content in 2 places and one of them still uses old branding of PortalJS
- Problem: this creates duplication and confusion
- Solution: migrate content over to github.com/datopian/datahub
docs
folder and then have that be the source of docs for datahub.io/docs
Situation
- portaljs.org looks quite good and works
- datahub cloud docs is just how to sign up and use the template
- Cloud docs are needed in terms of
- how to create visualizations
- how to use markdown
- portaljs.org site consists of …
- Home page: more of a pitch and already on datahub.io/opensource
- Docs = tutorial
- Components = storybook
- Examples = empty (should have stuff)
- Showcase = goes to home page
- Howtos = some actual howtos
- Guide = this is now makeitmarkdown
- Blog = should go to datahub.io
Problem
- Currently we have content in two places: portaljs.org and on datahub.io (and we want it in one place)
- We use PortalJS terminology in a bunch of places
- We aren't clear on how to prioritize self-hosted vs cloud which makes it unclear how to migrate docs (what comes on the landing page of the docs for example?)
- Docs are going to be stored in github.com/datopian/datahub repo in
docs
subfolder (?) but we aren't running off that atm
Other questions
- What is balance between self-hosted docs and cloud docs?
- current portaljs.org is focused on self-hosted …
- whilst new docs were focused on cloud
- Should we tag blog posts to label them with the relevant product?
Solution
- Merge all content from portaljs.org to datahub.io/docs - see fat marker sketch below
- Implement redirects (easy to do once we have this done)
Fat marker
- Home page: more of a pitch and moves to datahub.io/opensource (TODO? maybe
/self-hosted/
?) - Docs = tutorial =>
/docs/self-hosted
- Components = storybook =>
storybook.datahub.io
? - Blog = should go to datahub.io Move all the blog content over to DataHub blog (that's a simple copy and paste)
- Examples = empty (should have stuff) Drop for now as empty
- Showcase = goes to home page Goes to homepage and can keep it there for now
- Howtos = some actual howtos Move to blog posts with relevant tag? Or keep a a howto section. either way is good. Would slightly incline to blog route for now and having a howto page that links to all the blog posts …
- Guide = this is now makeitmarkdown Delete. Aside: we want to finish makeitmarkdown
Rabbit holes
- If we publish with DataHub we end up losing some nice features like … ✅2024-05-09 too bad, it's ok for now. Simple is better than perfect and eating our own dogfood is good! If we really want a proper blog page let's get ghost or something 😉
- Nice blog i.e. author images, nice listing etc – but maybe we bite the bullet on that (and we eat our own dogfood)
- General styling (but maybe who cares?)
ASIDE 🚩
general point. Yes … we can do a blog … but is that what we want to optimize for? We need to choose what we are focusing on and relentlessly optimize for that. 💬2024-05-09 that's true and for now let's live with the tool we have 😄