rocky-linux/documentation

write an article to describe the process of creating a new article

SergeCroise opened this issue · 2 comments

SergeCroise commented

Need to write a (style) guide to describe the process for creating new articles (how_to_write_a_new_rockydocs_item).
This guide (itself) is an example for the ideas to develop and discuss in this issue.

Ideas:

  • Describe basic principles (e.g., Liberté-Égalité-Fraternité)
  • Define concepts and terms
  • Describe the several steps of the process (of creating the new article)
  • Describe goals and quality criteria
  • Author considerations
  • Translator considerations
  • Review considerations

Steps

  • Issue: Write a (short) issue to announce the new article
  • First (new) Location(s): Decide where to place the new article (as such, new, e.g. documentation/new/.../.../<authors>/.../).
  • US-English: New articles may be written in any language, if not in english the rockydocs-team helps the author(s) to write the (US-)english version
  • Draft: at the beginning the new article is in state draft, does not need to be translated with crowdin
  • Proposal: after the author(s) have finished the new article, the Rockydocs-Team helps the author(s) to clean up the new article or if needed to write the (US-)english version.
  • Release-Candidate: after the (US-)version is in state "ready to vote", the whole Rocky Linux team (Translators, Authors, Reviewer, Developers,...) checks the new base article and vote (unanimously) to set to final state or set the article state back to draft (if the article is not understood from everybody). The Release-Candidate contains also a proposal for the final location.
  • Final location: if needed the article (in final state) is copied to the final location (e.g. in the case of new articles which are not originally written in english)
  • Ready to translate: the article state is in final state, stored at the final location.
  • Translations: the article in final state may be translated with crowdin
  • Cleanup first location: if needed, after a while, the new article at the first location can be removed

Proposal for the path (first location) of the new article (new)
documentation/docs/new/.../.../.../new-guides/neuer_artikel_prozess_beschreibung.md
documentation/docs/new/.../.../.../new-guides/processus_de_creation_de_nouvel_article.md
documentation/docs/new/.../.../.../new-guides/how_to_write_a_new_rockydocs_item.md

Proposal for the path (final location) of the basis article (ready to translate)

documentation/docs/guides/.../how_to....md

sspencerwire commented

@serge This is an interesting concept. I think that what we could do (and @wsoyinka could attest to this) a branch called " docreview" or something along those lines, that everyone would have read access and we (those editors, administrators with the current write access to the documentation repository) would have merge access in this new branch too. The difference is that no document would be refused at this stage. We would merge it into docreview and there it would receive the scrutiny you are talking about before it would be approved and a PR generated from this to documentation.

The downside of doing this, is that it could be a deterrent to contribution, and god knows we don't need any other deterrents to documentation.

Taking into account and writing additions to the style guide, so that they include logical paths (directories w/o spaces in them and lower case) as well as logical file naming (no capitals, lower-case, only underscores and dashes accepted as characters in the names, etc) would be written in. I think we do this even if we end up not doing the overall proposal here.

IF we use your proposal, I think we need to set a time-limit to the review and make sure that documents are quickly reviewed and approved or rejected so that contributors don't end up having their contributions languish in a no-mans land that we aren't paying enough attention to.

  • 👍1
SergeCroise commented

@serge This is an interesting concept. I think that what we could do (and @wsoyinka could attest to this) a branch called " docreview" or something along those lines, that everyone would have read access and we (those editors, administrators with the current write access to the documentation repository) would have merge access in this new branch too. The difference is that no document would be refused at this stage. We would merge it into docreview and there it would receive the scrutiny you are talking about before it would be approved and a PR generated from this to documentation.

The downside of doing this, is that it could be a deterrent to contribution, and god knows we don't need any other deterrents to documentation.

Taking into account and writing additions to the style guide, so that they include logical paths (directories w/o spaces in them and lower case) as well as logical file naming (no capitals, lower-case, only underscores and dashes accepted as characters in the names, etc) would be written in. I think we do this even if we end up not doing the overall proposal here.

IF we use your proposal, I think we need to set a time-limit to the review and make sure that documents are quickly reviewed and approved or rejected so that contributors don't end up having their contributions languish in a no-mans land that we aren't paying enough attention to.

@sspencerwire , @Grammaresque , @gannazhyrnova , @wsoyinka , @alemorvan , ...
The aim of this issue (for now) is to start a discussion (in mattermost) about the need to define a process for new articles considering some ideas like:

  • the liberty to start new articles (maybe also in any language other than english)
  • minimal quality requirements before we start translations
  • motivate new authors, translators, reviewers to join and to contribute to the documentation
  • highlight the benefits for contributors
  • ...

https://chat.rockylinux.org/rocky-linux/channels/documentation