[Datopian PortalJS Hackathon no 1] Learnings

[demenech]

Our first-ever PortalJS internal Hackathon is finally over!

Besides once again thanking everyone who participated, we would like to share our learnings in this discussion.

Links:

• Landing page - https://github.com/datopian/portals-monorepo/discussions/369
• Tutorial feedback - https://github.com/datopian/portals-monorepo/discussions/384
• CKAN-backed data portal challenge feedback - https://github.com/datopian/portals-monorepo/discussions/385
• GitHub-backed data portal challenge feedback - https://github.com/datopian/portals-monorepo/discussions/386

Learnings

About running a Hackathon:

• We are now studying the possibility of having Hackathons as a process. It provides great benefits in:
  • Sharing internal projects with coworkers
  • Evaluating docs and developer experience in general
  • Finding bugs
  • Spotting issues that are easier for outsiders to perceive
• When organizing a Hackathon, have in mind that some participants are going to commit themselves a 100% to the challenge! ...so, do your best and take it very seriously.
• Instructions have to be VERY CLEAR, otherwise, it's very likely that people will miss steps.
  • Make sure that all the instructions are on a single page/list
  • Provide examples for the tasks e.g. the architecture diagram, what a metadata showcase should look like
• Have a video call and ask participants questions, it's very insightful.
• We had some issues with collecting feedback from participants, mainly due to the instructions being a bit too complex (e.g. multiple GitHub discussions). The lesson here is: before letting participants leave, make sure they provided the expected feedback and, if you really want something, ask multiple times.
• People are unlikely to do optional stuff and to join optional events, so you have to make it as interesting as possible (and bug people a bit if necessary 😆)
• The participants without a FE background had a lot of fun and provided insightful feedback, especially about our docs. Having a wide range of backgrounds is positive, and folks are going to have fun trying out stuff they've never seen before (of course, as long as the Hackathon is now about something very specialized).

About the current state of PortalJS:

• At the start of the Hackathon we had an issue with our Learn example. What happened is that after updating the components package, the Learn example would build and deploy without any issues, but after accessing the deployment, the components were not being rendered correctly. Since we have multiple examples, we should transform our tutorials into test cases, so that we do regression testing on examples and ensure we are not breaking anything when the package is updated.
• Tutorial
  • When using Vercel deploy buttons on tutorials, we should position the button at the start of the tutorial. Vercel does not allow deploying an existing repo with the deploy button, so it gets very frustrating for people following the tutorial when they get to the deploy button and have to create a new repo.
  • We could make the tutorial project more interesting e.g. make it use real data
  • Finish each tutorial with conclusions
  • The documentation that we have as a Storybook project is not as obvious to most people as it's to us. There are many ways to make Storybook more interesting e.g. add more text content
• We have to start doing cross-browser testing. Many aspects of the project are being impacted by this on browsers other than Chrome.
• Package
  • Data components are missing loading indicators
  • We need to support more chart types, otherwise, people are obligated to use Vega, which is very unfriendly.
  • We should start thinking about ways to support theming on the components or ensure that components are more neutral when it comes to colors and style.
• Examples
  • Our examples could have a more unified theme and feel

[demenech]

CC: @anuveyatsu