🌐 Safe open information

Vision

Expand sources of knowledge while maintaining a high-quality of information

The long-term vision of open information (OI) is to expand the ability to collaborate. Open information include relevant outside resources, context, and etc. with X times the brain power in real-time with collaboration vs. single sources of truth.

Community collaboration

Incorporating the community of users, SafeDAO Guardians, and core team into the editorial process so they can approve certain types of updates are great points added by @DefiDebauchery here and @links here in the Discord # governance channel.

@theobtl started a conversation on this topic in the same channel and this is a place to capture our thought process and narrow down solutions.

Platform features

No existing platform has all of these features and some features have not been fully created yet.

  • Sign in with Ethereum (SIWE)
  • Sybil resistant verification
  • Markdown based content
    • GUI to handle Markdown
    • .md file type
  • Page features
    • Table of contents (ToC)
    • Deep-link to HTML ids, e.g. headers
    • Template library based on use case/topic
  • Git based versioning
  • Arweave and/or IPFS storage integration
  • Deep-search all pages
  • Track user’s contributions
  • Offline
    • Exports and imports of .md file types
    • Viewing and editing
  • Custom URLs
  • Customizable UI

Inspiration

Samples

I’ve created open info from official documentation and other community related sources. I’m looking forward to moving away from Google docs towards a platform with more of the attributes defined above.

9 Likes

Promising Markdown solutions

TLDR

  • GitBook
    • Seems to be a more common standard across software and crypto teams.
    • Has some clunky UX elements and things that’d be nice if they could be customized.
  • HackMD
    • After creating my first full HackMD page it has the best end user UX. The published page is fully reactive to any re-sizing with navigation elements transformed into useful buttons. This is the best balance of clean published UX, VCS integrations, and potential for future customization.
    • Lean product and engineering team.
    • Love the clean design of the published pages, Ethereum Foundation adoption, and great use case examples.
    • More customization with GUI editor due to direct Markdown access. Further Enterprise customization.
  • Notion
    • Incredible editing and published UX.
    • Does not seem to have VCS integrations.
  • Skiff
    • Closely matches crypto ethos: Sign-in with Ethereum (SIWE), IPFS hosting, Ethereum Naming Service (ENS) support, and etc.
    • However, pages still are in an early version with not a lot of customization or integrations yet.

HackMD

  • Notes: hackmd.io/@openinfo/hackmd
  • I’ll reach out to connect with their team as it’d be great to learn more about Enterprise features.
  • Hybrid user interface for editing pages without knowing Markdown
    • Customizable with direct Markdown editing
  • Cleaner more minimalist design options
  • Mobile app: None
  • Version control systems (VCS)
    • GitLab (Open-source :raised_hands:t2:) only available with Enterprise account
    • GitHub
  • Multi-factor authentication (MFA): No built-in solution. Need to research further.
  • Sign-in with Ethereum (SIWE): No.
  • Custom links
    • Custom readable links by default
    • Can link custom domain with Enterprise plan

GitBook

  • Notes: openguide.gitbook.io/gitbook
  • Great user interface for editing pages without knowing Markdown
    • Although hard to see table of contents (ToC) in edit mode since it disappears if the window is not close to full screen.
  • Clunky published UI compared to more minimalist cleaner Notion and HackMD designs
    • 2 sets of navigation menus
    • Large branding logo (Potentially can remove in Markdown code in GitLab/GitHub and push new commit)
  • Mobile app: None
  • Version control systems (VCS)
    • GitLab (Open-source :raised_hands:t2:)
    • GitHub
  • Multi-factor authentication (MFA): No built-in solution. Need to research further.
  • Sign-in with Ethereum (SIWE): No.
  • Custom links
    • Custom readable links by default
    • Can link custom domain

Notion

  • Notes: openguide.notion.site/openguide/Notion-f2be2968060847d08307f685d2af861d
  • Great user interface for editing pages without knowing Markdown
  • Cleaner more minimalist design options
  • Mobile app: Great UX
  • Version control systems (VCS)
    • Does not appear to support two-way syncing. Only pulling info from repositories issues.
    • Need to research if this is possible. Otherwise, this seems like a blocker in moving forward with Notion.
    • GitLab (Open-source :raised_hands:t2:)
    • GitHub
  • Multi-factor authentication (MFA): Need to research further.
  • Sign-in with Ethereum (SIWE): No.
  • Custom links: Need to research.

Skiff

  • Notes: Skiff
  • Great user interface for editing pages without knowing Markdown
  • Published UI is a bit clunky
    • Log in and join banner and footers
    • Empty “Add icon” potential UI bug
  • Mobile app (Haven’t tested yet)
  • Version control systems (VCS): None
  • Multi-factor authentication (MFA): Yes. Time-based One-Time Password (OATH-TOTP)
  • Sign-in with Ethereum (SIWE): Yes.
  • Custom links: Available for email. Potentially will come to pages at some-point.
2 Likes

We be on the same wavelength or something LOOOL

The very first thing I ever wanted to make was a general knowledge compendium but then realized that was impractical to start so went with a niche area to begin. I figured to go with quality knowledge hosted in a large bank. Anyone could reference the information stored, it would be verified by community members and actively curated/maintained.

I have experimented with Notion for my own project and came up with a kind of community center that doubles as a page to aggregate information about web3/crypto— at least, in relation to the project I’m building: DecentrAgora Community Center

I’ve really enjoyed the flow and having designed documentation with Gitbook and Docusaurus I’ve found that Notion adds a bit of flare that is generally fun to use.

Recently a few different things have made me think about this as well. There is a general need for an Eth hub that’s always accessible

I know Eth Hub was winded down with the intention that Ethereum dot org would maintain a knowledge bank but they need a lot of help with this too so it’s certainly worth it to explore

The Ethereum websites repo had over a hundred open issues when I last checked and not long before that it was 200+

Love the initiative frens @adamhurwitz.eth , @theobtl :saluting_face:

2 Likes

Thank you for sharing your experience with Notion and kind words @raynemang! I’ll take a look at the DecentrAgora pages the community has built.

  • Have you used or do you know if Notion has two-way syncing with version control systems (VCS) like GitLab/GitHub repositories?
  • This is important to back up the entire contents of projects and provides a path to decentralize in the future because VCSs can be automated to deploy and host content to IPFS and Arweave in a future more decentralized version of this info.

The ethereum.org UX is incredible! :pinched_fingers:t2:

  • Does anyone know who builds the site and if they code it natively or if they use an easy-to-use content platform like one of the ones mentioned above to abstract the code?
1 Like

You’re welcome ser! :saluting_face:

That’s a good question, I know there are a number of integrations usable with Notion and Github is one so I suspect there would be a way to sync data across the two places

I’m unsure about the version control, but I do know you can look through an audit log on Notion and view previous versions

Agreed! Love the Ethereum website, it’s brilliant — the only reason I found there were a pile of pull requests for review was because I wanted to contribute to the front end :rofl:

They just had a community call in their Discord where they talked a lot about creating frameworks for contributors, it sounds like they are making pushes towards bringing in more of the community to help maintain the website; more than 1000 people have contributed to the website :sweat_smile: (this number probably counts other repos as well)

2 Likes

Wow. Impressive that 1,000 individuals have contributed to the Ethereum Foundation (EF) site. That’s awesome the EF is thinking about building frameworks for future contribution.

My question on version control is not on whether you can look at the Notion history. Rather, if you can push and pull commits to a GitLab/GitHub repository. I’ll explore and test this further. @links may have experience with this too.

1 Like

Agreed ser!

It lists the number at the bottom of that page but I’m not sure if it’s across all repos— either way I certainly agree, very impressive

Ahh roger that, I know you can integrate Github or Gitlab and get feeds from commits or open PRs but unsure if you can push them

This may help your question: GitHub Integrations | Connect Your Apps with Notion

1 Like

FYI, I took a quick look at the EF site’s repository and it is built natively. That is, they currently don’t use a platform to abstract away the code.

See The ethereum.org website stack

2 Likes

Pretty sure you can’t do this with Notion! It’s a shame that the most usable, accessible wiki system is also the most centralized/closed, but I guess that is to be expected =x

That being said - is this push/pull via Git repo the feature you specifically want? Or more about the ability to import/export/have a text version/have a diff-able copy?

2 Likes

ahhh good to note! thank you ser :saluting_face:

Pretty sure you can’t do this with Notion!

I’ll research the API docs further and follow-up on their StackOverflow, Slack, Twitter, and support email.

UX

After building my first HackMD page (hackmd.io/@openinfo/hackmd) the published UX is better than Notion’s because of its ability to adapt to any screen size.

  • HackMD is the only platform so far where I can easily copy and paste published content. I’m having issues on other platforms in Firefox with highlighting content with texts and links.
  • The hybrid GUI/Markdown editor allows direct access to the Markdown which is powerful for customization beyond other platform’s GUIs for colors, themes, templates, and etc.
  • Next I’ll refactor the HackMD page to a Book view to test out multi-pages and the collapsible navigation menu.
  • It could be a good opportunity to grow alongside their small and effective team.

I am enjoying GitBook more that I discovered their Editorial Page Layout that has 1 sidebar for the ToC instead of 2 sidebars including an additional navigation menu. I’ve updated the sample above to include this.

  • An issue is GitBook’s ToC disappears unless the window is almost completely expanded in the published view so many users will likely miss this component.
  • Ideally, the additional navigation menu would be collapsible like in HackMD’s book view, e.g. Ethereum Improvement Proposals Insight.

VCS

My assumption is that the version control system (VCS) is important in the long-term for automating tasks and for decentralization. With continuous integration (CI)/ continuous deployment (CD) tools we could auto-deploy to platforms like Arweave and IPFS in the future.

Long-term vision

  1. DAO collaborates on content in a Markdown based app, e.g. HackMD, Notion, Gitbook, Skiff, and etc.
  2. Commits from the app are pushed to a VCS feature branch.
  3. The feature branch is merged to a release branch.
  4. The release branch auto deploys the changes to Arweave/IPFS for updating the publicly available content.
2 Likes

I’ve refactored the HackMD info into a “Book” format to showcase the navigation menu for multi-page collections.

Navigation menu

Open and toggle for navigation menu to close

|

Mobile

HackMD looks great in the Firefox mobile browser for reading and surprisingly for editing too with a view/edit button to easily switch back and forth.

| |

Next steps

  • Look into some of the open questions on the other platforms above around VCS and customization.
  • Test HackMD color, style, and theme customizations.
  • Reach out to HackMD to learn more from their Enterprise team.
2 Likes

Thanks for all the effort you are putting in testing solutions! I will have to check out HackMD when I get a chance

2 Likes

HackMD update

  • I’ve created a SafeDAO specific prototype to build off of the generic HackMD prototype that covers HackMD’s features and opportunities.
    • I used the direct access to Markdown to customize some HTML and CSS.
    • Much more can be done with the enterprise account.
  • I had a video call with HackMD product manager, Elek Li, on HackMD UX, what works well, and what to improve. Elek will connect me with the team to learn more about enterprise capabilities.
  • I will reach out to relevant teams that are using HackMD to learn about their experience.

Core Safe team

1 Like

This is amazing @adamhurwitz.eth ! I love the initiative.

My recommendation is that we move the Safe Open Guide to Github.

  1. Many people are already familiar with Github’s UX and already have a Github account
  2. Content on Github is open-source and version controlled so there is no lock-in and we can export to another format in the future.
  3. Github is very popular so there are more tools that we can use for Github integration (Zapier, Notion etc.)

HackMD is a fne tool for people already in the blockchain ecosystem but for people less familiar I feel like it’s another point of friction and increases barrier for entry for more people to collaborate.

My recommendation:

  1. Move the content to Github, we can put it in safe-docs or I can make a new Repo and you can add content there. I’m thinking https://github.com/5afe/safe-wiki.
  2. Look into tools to allow syncing content between Github and other no-code solutions like Notion.

I think it’d also be really cool as a next step if Github was the canonical source of truth for the content but we also allow for 2-way syncing with no-code tools like Notion. For example, people could browse the content in Notion and also allow people to contribute to the open guide using Notion’s popular WYSIWYG editor.

Some resources worth exploring:

  1. How to Sync Notion With Github Repositories (2 Methods)
  2. Connect your GitHub to Notion integration in 2 minutes | Zapier
  3. GitHub - the-guild-org/notion-github-sync: A CloudFlare Worker / script / bot to sync Notion pages publicly as GitHub Discussions.
  4. Notion x GitHub Action · Actions · GitHub Marketplace · GitHub

Thank you @tomiwa1a!

The most important thing is effectively coordinating across the core Safe team, SafeDAO, and community. I’m looking forward to merging the existing open notes with whichever platform we decide on.

Version control systems (VCS) two-way sync

I agree on optimizing for a Markdown tool that works seamlessly with VCS two-way sync.

Benefits

  • Allows for automating backups
  • Manage versioning
  • Allows contributors to use their client of choice.
    • Those comfortable with Markdown + Git can write custom Markdown and submit pull requests with their editor of choice.
    • Beginners can write directly in a WYSIWYG editor.
  • Future optionality to auto-publish with custom hosting

GitHub

  • GitHub makes sense in order to optimize for current developer adoption.
  • “We can export to another format in the future.”: I like this idea.
    • GitLab: Dedicated to open-source/open-core
    • Radicle.xyz: Open-source + working on decentralization

Notion
Thank you for pointing me in the right direction for Notion<>GitHub syncing. Scanning the Notion docs so far I did not see a native way to implement GitHub two-way sync. I’ll start with these resources and explore further to see if a seamless workaround can be made.

Overall, I enjoy both the final published version and editing experience of Notion over GitBook. Although, not as much as HackMD for each category. Notion could be a good balanced option given two-way VCS sync is possible.

GitBook and HackMD
Both platforms currently have VCS two-way sync.

WYSIWYG

This is the term I’ve been looking for recently that I didn’t know existed! So far I’ve been calling this “GUI to handle Markdown”.

How important is WYSIWG for Safe open info?

  • If we’re optimizing for WYSIWG then HackMD is likely not the best solution to your point because it requires using Markdown directly.
  • Users with any technical experience may be familiar with Markdown from Reddit, GitHub, StackOverflow, and etc. However, this may be a limiting factor for non-tech beginner users.
  • Is this the point of friction you referred to for HackMD or are there other issues as well?
  • I wouldn’t categorize HackMD as a blockchain specific tool. The EF and Consensys examples I used because they’re a similar use case. However, the platform is a generic Markdown publishing tool.

HackMD split view editor

I parsed through the Notion<>GitHub workaround links above. Unfortunately, they evolve around syncing GitHub issues with Notion whereas we’re looking to push and pull our Markdown .md files with GitHub. This still might be possible with a custom API integration, but so far it seems it would not be as seamless as GitBook or HackMD for two-way sync.

As @tomiwa1a, @theobtl, and I have discussed, the next version of the proof-of-concept open info (OI) for Safe and SafeDAO have been created in GitHub with Markdown. I’ve further experimented with HackMD’s published UI which is synced to each GitHub repository in HackMD’s app.

Migration to Safe resources

  • I can incrementally submit pull requests to merge the content from the open info into core Safe team/SafeDAO resources.
  • I’m happy to migrate the Markdown files from the repositories (repos) below to the SafeDAO team’s repos once they’re created.
  • I’ve also created HackMD public teams for Safe and SafeDAO that can have an unlimited amount of contributors. I can transfer ownership of these team accounts too given the relevant email address(es) of the core team.

Safe ecosystem

Edits made

  • Cleaned up Google doc to Markdown conversion
  • Refactored from 1 long page into topic-based pages organized by categories: About, Use, Compatibility, and Security
  • Updated links from Gnosis to Safe scheme

SafeDAO

Edits made: Migrated from Google document

I’ve also created a pull request to update the link to my authored Safe Open crypto info under the Resources section.

Minor update: I’ve updated the naming convention from “open guides” (OG) to “open info” (OI).

“Guide” seems to suggest providing advice and feels more appropriate for a centralized entity. The vision is to move towards more open and decentralized collaboration which is potentially better fitting for the naming convention of “open information” (OI).

The reason I’m thinking about this today is because I’m submitting an idea to Ethereum Foundation’s (EFs) Summer of Protocols (SoP) program on Opening and decentralizing collaboration protocols. :sunny:

2 Likes

I like this, and completely agree more clear information would be helpful. Easy digestible learning opportunities (similar to coinmarket’s alexandria) are the key to helping everyone understand Safe and that is what leads to adoption and engagement.
Apologies if I missed it, but one area I wanted to call out that could use more clear (less-technical) details are items like Safe Modules and Transaction Guards. These are valuable resources with all the scams out there, but also dangerous if used incorrectly. So it would be wonderful to find a way to bring that knowledge to the average user.

2 Likes