Welcome to the Cloud Security Alliance Guidance 4.0 project on GitHub. Here is how to participate:
- We need your feedback!!! Although we have a dedicated writing team, this is still a community project. The idea is to generate a cleaner and more consistent document than possible by solely relying on working groups to do their own writing, while still reflecting the collective wisdom of the community.
- All feedback and edits will be managed via GitHub so that all parts of the process are open and public.
- You don't need to use any special command-line GitHub tools for this project. GitHub's web interface will allow you to read documents, provide feedback, and participate. But feel free to use git tools if you know how.
- Here is how to use GitHub to provide feedback:
- Issues are the best way to add comments. The authors can read and respond to them directly. When leaving an issue. please list the line number for the start of any specific section you are commenting on.
- Pull requests are for edits. We can't respond to all pull requests because our only options are to ignore a pull or merge the changes. For consistency's sake, it is very hard to accept pull requests directly. All pull requests will be reviewed, some will be merged, and those we cannot directly merge will be treated as an issue/comment and closed. This is just a practical necessity, considering how many people will eventually be providing feedback.
- For writing we are using the Markdown text format. If you want to edit and send pull requests you will need to learn Markdown (fortunately it's incredibly simple). GitHub renders Markdown directly, so unless you are actually editing content you won't need to learn it.
- Keep all feedback public, on GitHub. This is essential for maintaining the independence and objectivity of this project. Even if you know any of the authors or CSA staff, please don't email private feedback, which will be ignored.
We will do our absolute best to respond to all feedback (with the exception of pull requests, which we will review), but depending on volume we may need to combine feedback (and we understand some feedback will be contradictory).
Here is what you can expect:
- We will have a separate file for each domain in the Guidance.
- For each domain, we will first publish a detailed outline with expected changes, and then drafts. Domains will be open for feedback the entire time, but may be closed temporarily during specific writing phases (e.g., after we collect comments on the outline, the author may close feedback as they develop the first draft).
- For each domain, there will be an outline, first draft, and near-final draft.
- The exception is Domain 1. We skipped the outline for that and went straight to the first draft to set a writing tone for the rest of the project.
- The near-final drafts will be pulled from GitHub and converted into Word, with updated graphics, for final publication.
If you have any questions or general comments, please let us know either here or through email to guidance@cloudsecurityalliance.org, and thank you for your help.
- All images should be placed in /images and named with the section they appear in, followed by a dash, followed by an enumerator. e.g. "1.1.2-1.png" for the first image in the directory. Please use standard Markdown image embedding.
- Links should be referenced, not inline. Each link should be sequentially ordered. This makes things easier to read (look at Domain 1 for formatting examples -- it's easy). If links start getting out of order, feel free to use "1.1" or similar to neaten things up.
- Images will be redone by a graphics team before publication, so don't worry about having them look consistent.
