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 😄

Built with DataHub LogoDataHub Cloud