This is a work in progress and not a release. We're looking for volunteers. See Issues to know how to collaborate.

Contribute to the Security Framework

The Security Framework is an open and collaborative project. Whether you are part of the Security Alliance or not, we welcome your contributions! Help us to build the documentation and improve security in the ecosystem.

This mdBook-style handbook is designed for easy collaboration and automatic deployment through continuous integration. If you'd like to join our effort, feel free to fix typos, contribute new sections, or propose enhancements.

To contribute you can either:

  • Fork this repository, switch to the develop branch, and submit a pull request.
  • On each page, you will find a "Suggest an edit" button at the top-right corner. Clicking this sends you to the GitHub.com where you can suggest edits using their web interface.

Contributing

Before you start editing, adding or removing content, please read the [code of conduct]https://github.com/security-alliance/frameworks/CODE_OF_CONDUCT.md and make yourself familiar with the overall structure.

The source is hosted in github repository at github.com/security-alliance/frameworks.

The content of the Frameworks comes from the main branch, and when contributing we would like to you open a PR into the development branch.

Once a new update is warranted, the content from development is merged into main.

You may explore existing issues or open a new one for missing content, although a PR is preferred. If you identify missing or unfinished content, feel free to open a PR. First, check existing PRs or branches to make sure your work is not redundant.

Structure and collaboration

The wiki is supposed to cover all important parts of security for web3 projects. For contributors, we recommend focusing on specific topics contained in corresponding documents. It's best to own a single topic and work out all the details. Create a new document and add the topic to the sidebar if it's not there yet. Join the discord server, let others know what you are working on in the group channel and collaborate with other contributors writing about related topics. If you are working with multiple people on a significant piece of content, you can have a dedicated branch in the repo for easier coordination.

Style guide

Wiki pages follow standard Markdown with some extensions by mdBook.

The audience of this wiki is technical and the content should reflect that. There are many guides on technical and documentation writing you can learn from, for example you can check this lecture to get started.

Here are main guidelines to follow when writing this wiki:

  • Write in an objective, clear and explanatory tone
  • Avoid unnecessary simplifications, describe the technical reality
  • Avoid using too long and complex sentences or paragraphs
    • Use concise and clear statements
    • Break down your text using block-quotes, bullet points or images
  • Always link your resources and verify them
  • Use bullet points or tables for topics which require enumerating
  • Highlight keywords to support scanning and skimming through the article
  • Provide visualizations to explain the topic better
  • When using acronyms or a technical jargon, make sure to introduce it first
  • Web3 is changing fast, write the content to be as much future proof as possible
  • Don't use LLMs to generate the text
    • We don't accept texts fully generated by AI, however we recommend using it to fix grammar or phrasing
  • Consider creating tutorials and hands-on guides documenting technical steps
  • Add recommended reading at the top, point to topics which are dependencies of yours
  • You can use mermaid diagrams for visualizations

Goal is to produce a credible neutral text which is formal, well-structured, and maintains a clear progression of ideas. The content should be purely technical and shouldn't waste space on introducing high level/well known concepts. Introductory topics are necessary and can use comparisons, historical anecdotes, and concrete examples to make complex concepts more accessible.

Content standardization

The wiki uses American English over British spelling. Terminology, capitalization and nomenclature should match across all pages. Use Ethereum.org guide for the reference.

Usage of images and visualizations is encouraged. If you are using an image created by a third party, make sure its license allows it and provide link to the original. For creating your own visualizations, we suggest excalidraw.com.

Feel free to use emojis or icons where it fits, for example in block-quotes.

Linking resources

When adding an external link, you can use it directly in the text or on the bottom of the page in "Resources" section.

When linking resources use descriptive names, such as inevitableeth.com instead of generic phrases like this wiki.

Don't overwhelm reader with too many resources within the text.

When linking a page within this framework, use a relative path and if it references specific topic within the page, use a link to heading IDs.

For other important links, add a section on the bottom of the page with list of resources. Resources should have a name or short description with a link and alternative link to its archived mirror. We strongly suggest adding a link to the latest snapshot from archive.org.

In-page notices

We use block-quote notices at the top of the page to provide readers with appropriate context regarding the content of the page.

Incomplete pages

Pages with minimal content which need more work to cover the topic need to include a notice:

> :warning: This article is a [stub](https://en.wikipedia.org/wiki/Wikipedia:Stub), help the framework by [contributing](/contribute/contributing.md) and expanding it.

Anything else?

This page is also opened for contributors! Suggest improvements to our style and guidelines in the github repo.

Attribution

A lot of the content of this page comes from the Ethereum Protocol Fellows