-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Pull authoring and contributing apart from README
Create a CONTRIBUTING.adoc file in every language.
- Loading branch information
Showing
7 changed files
with
336 additions
and
85 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,131 @@ | ||
| = New document template | ||
| // tag::metadata[] | ||
| :lang: en | ||
| include::../locale/attributes.adoc[] | ||
|
|
||
| This repository is meant to be https://help.github.com/articles/importing-a-repository-with-github-importer/[imported] (instead of cloned/forked) to create a new document for the Decidim project. | ||
| // MANDATORY. URL pointing to a Git repository with the source code of the | ||
| // document. Something like 'https://github.com/decidim/docs-features'. | ||
| :_public_repo_url: | ||
|
|
||
| // MANDATORY. Title of the document. In web format, It appears as a heading of | ||
| // level 1. In PDF format, it appears in a title page. | ||
| :_title: | ||
|
|
||
| // OPTIONAL. If not blank, it must begin with ": " (colon followed by a blank | ||
| // space). In web format, it appears as part of the same heading of level 1 than | ||
| // the title. In PDF format, it appears in the title page, just below the title. | ||
| :_subtitle: | ||
|
|
||
| // It's usually not necessary to change this field. | ||
| :doctitle: {_title}{_subtitle} | ||
|
|
||
| // MANDATORY. Numeric revision in X.Y.Z format, where X, Y and Z are numbers, | ||
| // and Z is optional. | ||
| :revnumber: 0.1 | ||
|
|
||
| // OPTIONAL. Publication date of the revision. When the default value | ||
| // ("{docdate}") is used, the current date in format YYYY-MM-DD is automatically | ||
| // inserted in this field every time the formatted document (web or PDF) is | ||
| // generated. It's also possible to manually write here a fixed date. | ||
| :revdate: {docdate} | ||
|
|
||
| // OPTIONAL. See this field description in section "Authorship criteria ..." | ||
| // below. | ||
| :_editors: | ||
|
|
||
| // MANDATORY. See this field description in section "Authorship criteria ..." | ||
| // below. | ||
| :authors: Decidim Team | ||
|
|
||
| // OPTIONAL. See this field description in section "Authorship criteria ..." | ||
| // below. | ||
| :_contributors: | ||
|
|
||
| // OPTIONAL. See this field description in section "Authorship criteria ..." | ||
| // below. | ||
| :_proofreaders: | ||
|
|
||
| // OPTIONAL. See this field description in section "Authorship criteria ..." | ||
| // below. | ||
| :_participants: | ||
|
|
||
| // MANDATORY. Summary of the contents of the document. This would correspond to | ||
| // the "abstract" in an academic publication. | ||
| :_summary: | ||
|
|
||
| // MANDATORY. Comma-separated list of terms to help classifying and searching | ||
| // the document. In web format, this terms are integrated as SEO enabling | ||
| // metadata. In PDF format, they are shown near the other metadata. | ||
| :keywords: decidim, participatory democracy, free software, open source, cities, organizations | ||
|
|
||
| // OPTIONAL. Document's history. | ||
| :_dochistory: | ||
|
|
||
| // MANDATORY. When the document is not in its 1.0 release, yet, we can write "WE | ||
| // URGE YOU NOT TO CITE THIS YET UNTIL REVISION 1.0" Variables like {_title}, | ||
| // {authors}, {doctitle}, {revnumber} or {docyear} can be used here. | ||
| :_citation: {authors}, {docyear}, {doctitle} | ||
|
|
||
| // MANDATORY. Copyright ownership. | ||
| :_copyleft: Barcelona City Council and the authors of the text | ||
|
|
||
| // MANDATORY. Distribution license. | ||
| :_license_1: Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA-4.0) | ||
|
|
||
| // OPTIONAL. Alternative distribution license. | ||
| :_license_2: GNU Free Documentation (GFDL-1.3-or-later) | ||
|
|
||
| // end::metadata[] | ||
|
|
||
| // tag::page-title[] | ||
|
|
||
| = {doctitle} | ||
|
|
||
| {_summary} | ||
|
|
||
| This document is part of the https://docs.decidim.org[Decidim documentation]. | ||
|
|
||
| // end::page-title[] | ||
|
|
||
| // tag::metadata-table[] | ||
|
|
||
| == Metadata | ||
|
|
||
| [cols="20,80"] | ||
| |=== | ||
| | Title | {_title} | ||
| | Version | {revnumber} | ||
| | Date | {revdate} | ||
| | Editors | {_editors} | ||
| | Authors | {authors} | ||
| | Contributors | {_contributors} | ||
| | Proofreaders | {_proofreaders} | ||
| | Participants | {_participants} | ||
| | Summary | {_summary} | ||
| | Keywords | {keywords} | ||
| | Document history | {_dochistory} | ||
| | How to cite | {_citation} | ||
| | Copyleft | ||
| a| {_copyleft}, under a {_license_1} license | ||
| ifdef::_license_2[and a {_license_2} license] | ||
| . | ||
|
|
||
| [discrete] | ||
| ===== Creative Commons Attribution-ShareAlike 4.0 International License (CC-BY-SA-4.0) | ||
|
|
||
| You are free to copy and redistribute the material in any medium or format, remix, transform and build upon material, for any purpose, even commercially. The licensor may not revoke these freedoms as long as you comply with the licence's terms. Under the following conditions: a) Attribution: you must provide an appropriate acknowledgement of the authorship, provide a link to the licence and state whether any changes have been made. You may do that in any reasonable way, but not in a way that would suggest you have the licensor's support or receive it for the use you are making; b) ShareAlike: where you remix change or create from the material, you will have to disseminate your contributions under the same licence as the original. There are no additional restrictions, you may not apply legal terms or technological measures that legally restrict others from doing anything the licence permits. You can find full licences on the following links: https://creativecommons.org/licenses/by-sa/4.0/deed. | ||
|
|
||
| [discrete] | ||
| ===== GNU Free Documentation Licence (GFDL-1.3-or-later) | ||
|
|
||
| You are permitted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation Licence, version 1.3 or any other version subsequently published by the Free Software Foundation; without Invariant Sections or Front-Cover Texts, or Back-Cover Texts either. You can find a copy of the licence on http://www.gnu.org/copyleft/fdl.html. | ||
| |=== | ||
|
|
||
| // end::metadata-table[] | ||
|
|
||
| // tag::contributing[] | ||
|
|
||
| == How to contribute | ||
|
|
||
| See link:./CONTRIBUTING.adoc[Contributing]. | ||
|
|
||
| // end::contributing[] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| = Criteris d'autoria i com participar en aquest document | ||
|
|
||
| Aquest document està obert a la participació. | ||
| Si tens familiaritat amb Git i saps què és un _Pull Request_ pots clonar | ||
| ifdef::_public_repo_url[{_public_repo_url}[el repositori públic]] | ||
| ifndef::_public_repo_url[el repositori públic] | ||
| i començar a fer contribucions. | ||
| Si no, pots escriure'ns a hola@decidim.org. | ||
| Si us plau, consulta la nostra https://docs.decidim.org/editing-guide/ca/latest/index.html[Guia d'edició de documentació]. | ||
|
|
||
| Les contribucions poden ser de diversa naturalesa. | ||
| Els diferents nivells i criteris d'autoria s'expliquen a continuació: | ||
|
|
||
| Editor/a :: | ||
| S'encarrega del monitoratge del text, les seves versions, correccions, estructuració, etcètera. | ||
| Pot coincidir o no amb algun dels autors. | ||
| Es tracta, en definitiva, d'un coordinador de la col·laboració del text. | ||
| És funció de l'editor sol·licitar les revisions i llegir-les. | ||
|
|
||
| Autor/a :: | ||
| Són autors els qui pròpiament han redactat el text. | ||
| L'ordre dels autors en reflecteix la contribució; el primer nom és el de qui més ha escrit. | ||
| L’autor haurà llegit i revisat el text en la seva versió final o en versions anteriors, però no cal que estigui d'acord amb la configuració final del text. | ||
| Aquesta tasca queda en mans de l'editor. | ||
|
|
||
| Contribuïdor/a :: | ||
| Aquí poden considerar-se dos grups de contribuïdors. | ||
| D'una banda, les persones encarregades de la revisió acadèmica del document (en cas que la seva contribució sigui considerable) i, de l’altra, col·laboradors externs la contribució dels quals hagi estat valuosa i s'hagi consolidat en parts de text incloses al document. | ||
| La diferència entre contribuïdor i autor queda en mans de l'editor o de la resta d'autors però, en tot cas, la contribució ha de ser inferior a la de la resta d'autors. | ||
| Com a regla general, si un autor ha escrit menys del 10% del text s'hauria de considerar contribuïdor. | ||
| Al seu torn, ser contribuïdor requereix almenys haver escrit dos o tres paràgrafs. | ||
|
|
||
| Participant :: | ||
| Es tracta d'una persona que, sense haver contribuït amb una part de text específica al document, ha fet contribucions de valor, com ara comentaris pertinents, o ha proporcionat criteris, referències o elements de discussió valuosos. | ||
|
|
||
| Revisor/a :: | ||
| Aquesta tasca inclou una lectura minuciosa de tot el text, la correcció d'errors i la proposta de millores. | ||
| En general, és una feina per encàrrec (sol·licitada a una persona que es considera competent en la matèria), encara que és possible que algú contribueixi fent una revisió sense sol·licitud expressa. | ||
| En tal cas, la profunditat i qualitat d'aquesta es poden valorar per considerar aquesta persona revisora. | ||
|
|
||
| Aquesta divisió i especificació de nivells d'autoria s'ha copiat directament dels criteris establerts en el projecte http://floksociety.org/[FLOK Society - Buen conocer] (veure http://book.floksociety.org/ec/[el llibre del mateix títol, Barandiaran et al. 2015], pàgines 38-39). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| = Authorship criteria and how to contribute to this document | ||
|
|
||
| This document is open to participation. | ||
| If you are familiar with Git and Pull Requests you can clone | ||
| ifdef::_public_repo_url[{_public_repo_url}[the public repository]] | ||
| ifndef::_public_repo_url[the public repository] | ||
| and start contributing. | ||
| Otherwise, you can contact us at hola@decidim.org. | ||
| Please, have a look at our https://docs.decidim.org/editing-guide/en/latest/index.html[Documentation Editing Guide]. | ||
|
|
||
| Your contributions may be of varying nature. | ||
| The different authorship levels and criteria are stated below: | ||
|
|
||
| Editors :: | ||
| Responsible for monitoring a text and its versions, corrections and structure etc., and may or may not be one of the authors. | ||
| In essence, an editor is someone who coordinates collaboration on the text. | ||
| One of the editor's responsibilities is to request and read revisions. | ||
|
|
||
| Authors :: | ||
| Strictly speaking, authors are those who have drafted the text. | ||
| The order of the authors listed reflects their contribution, with the first mentioned being the one who has written the most. | ||
| Authors must have read and revised their text in its final or previous versions, although they do not have to agree with its final form, a task that falls to the editor. | ||
|
|
||
| Contributors :: | ||
| Two groups of contributors are considered here. | ||
| On the one hand, the document's academic revisers (where they have made a considerable contribution) and, on the other, external collaborators whose contributions have been valuable and integrated in parts of the text included in the document. | ||
| It is up to the editor and other authors to decide who is a contributor or an author, although the former is in any case meant to contribute less than the latter. | ||
| As a general rule, a person who has written under 10% of the text ought to be considered a contributor rather than an author. | ||
| By the same token, being a contributor means having written at least two or three paragraphs. | ||
|
|
||
| Participants :: | ||
| This is someone who has not contributed any specific text to the document but who has made valuable contributions such as observations about the document or provided valuable criteria, references or elements of discussion. | ||
|
|
||
| Proofreaders :: | ||
| Their work includes carefully reading an entire text, correcting errors and suggesting improvements. | ||
| Such work is generally commissioned (requested from a person regarded as competent in the field), although it is possible for someone to contribute by proofreading a text that has not been explicitly requested. | ||
| In such cases, the depth and quality of the proofreading process may qualify a person to be considered as a proofreader. | ||
|
|
||
| This division and specification of authorship levels has been directly copied from the criteria established under http://floksociety.org/[the FLOK Society - Buen conocer] (see http://book.floksociety.org/ec/[Barandiaran et al. 2015], pp. 38-39). |
Oops, something went wrong.