agracia
commented
11 years ago OK!!, the processes are explained in two different documents. The 'Revision process' ad 'Review process' are available as well as a short summary of the two processes (Revision_Review_Process document).
Please check the documents in
https://github.com/openETCS/governance/tree/RC_ReviewProcess_01/Review%20Process/Review%20Documents
This document is called “Project Quality Assurance Plan - Review Process”, however it describes a MIXTURE of “Revising” (= Rework) and “Reviewing” (coming from “view” = looking at something, "A second or subsequent reading of a text or artifact." or "... a critical evaluation of a text or a piece of work." or "(law) A judicial reassessment of a case or an event." ==> see: Wikipedia "Wiktionary"). That means a "Review" has nothing to do with "Rewriting". Those two activities should be strictly separated. By separating them, also different sets of tools can be identified. Nevertheless the document could handle both activities in one document (I wouldn’t) however then it should be called “ … Revising & Review Process” BUT both activities need to be described in separate chapters. (I would not recommend that due to several reasons) *) The “Revising Process” needs – equally like the original creation process of a document - tools for editing and (PDF) document generation, however the pure “Review Process” does not need any editing tools. The “Review Process” can rely on the use of the issue tracker itself. Even longer textual artifacts or sketches and drawings can be handled with the issue tracker alone. In addition the issue tracker gives the opportunity that the other reviewers can comment on this issue. Change requests can also be evaluated by others AND reviewers do not need specific skills or training for working with the issue tracker. See picture enclosed for process details and workflow with revising and review steps. . The “Review Process” should be strictly limited to “Review” activities (= reading and giving comments). Here three types of reviews can be distinguished:
1.) A pure “internet review” process. That means all activities are done via the internet and by using the issue tracker only. The person who has created the document to be reviewed has to upload it in PDF and LaTeX format onto a dedicated repository, calls for a review and sets a deadline (milestone) until all responses have to be entered into the issue tracker. He or she sends a mail to all potential reviewers he/she wants to have feedback from. After the deadline has expired the creator of the documents evaluates all issues, decides on whether they get considered or not. If the issue gets ignored the creator of the document owes the issue writer at least a short justification why the issue was not considered for any changes inside the document and “closes” the issue. The issue author should have a sufficient period to react on this response. Questions need to be answered.
2.) A “online review” process witch, starts identical with the “internet review”, however with publishing the document under review a doodle poll should be posted for an online meeting (< 20 attendees) or webinar (> 20 attendees) shortly after the expiration date of the deadline. All issues need to be commented in writing by the document author before the online meeting/webinar. During the online meeting/webinar the document author reads all text section which was subject to the issue and gives a comment. Attendees should have an opportunity to respond to those verbal explanations. Minutes of the meeting need to be created and uploaded to the same repository within 24h. After that online meeting/webinar all agreed changes have to be incorporated into the document.
3.) A ”classical face-to-face review” will be exercised in the same way like the “online review” except that instead of an online meeting/webinar a face to face meeting will be arranged. This type of review should be used only for very critical documents or documents which had at least 2 online or internet reviews but are still questioned by more than one of the stakeholders (customers, project leaders, work package leaders, or task leaders).
For all above mentioned reviews the only tools to be used by the reviewers are a PDF reader and an internet browser. Some kind of editor or drawing tools might be helpful for more elaborate text or graphic contributions, but is not required to make valuable contributions. Since an review is always also some kind of an assessment of the reviewd text or artifact, each reviewer should be asked to give a verdict like:
1.) Ready for official release without change, 2.) Ready for official release after certain (minor) changes as specified have been incorporated, 3.) Not Ready for official release, need futher (major) re-work (revising), 4.) Not at all ready, even not after improvement, further work to be cancelled, document gets "frozen" and archived.
See process picture below.
*) My personal recommendation would be to make two different documents out of it, simply because different groups of people are getting addressed: The “Revising Process” is exercised by Committers who have full access rights (Pull & Push) to the repository or Contributors who have only pull rights, but can branch a document and push it onto their own repository, but not into the official openETCS.org repository since they have not (yet) qualified as “Committers”. However both groups need to use creation and editing tools (LaTeX tools and Git or SmartGit or similar) and both groups need to make IPR agreements with the openETCS project consortium, if their contribution are not considered as minor (less than 200 characters). However the typical expert “reviewer” is only asked to read the document and give their feedback. They just download and open the PDF document, reading it and whenever they think something may need improvements, they give a feedback, which might be just a comment or a minor contribution, e.g. how to better rephrase a chapter etc.. They can do that by open up an issue on the GitHub issue tracker and write their comment. They can cut & paste phrases from the original PDF document and enter a rephrased proposal into the issue tracker. Those reviewers do not need to modify LaTeX documents, so they do not need to bother with any other tools or uploading procedures. All they need is an state-of-the-art internet browser. Only what we want is their feedback and that should be made as easy as possible, however fully traceable and visible to other reviewers, so that they can give their further comments on that issue as well. And it should be individually tracked and followed up with. Even after the end of the review it should be visible to all experts: What has happened to that issue, and when has it been closed and by whom. All that can be done easily with the issue tracker in GitHub alone and it requires almost no training for normal computer-literate persons to open an issue. It is then up to person responsible for the document to 1.) Respond to this issue, 2.) Decide whether or not it will modify the document, 3.) Act accordingly, and then 4.) Close the issue.
Having a separate very slim instruction for reviewers with only that few steps, will increase likelyhood that experts, even those not being very familiar with open source project practices, beeing able and willing to contribute (BTW: “review sheets” becoming much too cumbersome to maintain if they are set up for doing the same thing in the same quality.). Therefore a separate “Review Process” and Instruction Document, separated from the “Revising” Instruction Document is highly recommended.