-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"index.html","title":"Home","text":""},{"location":"index.html#welcome-to-osep","title":"Welcome to OSEP","text":"<p>This is the home of the Open Source Engineering Process (OSEP) working group, part of the Linux Foundation's ELISA project</p> <p>This working group examines how software engineering processes can be used to facilitate the certification of safety-related systems incorporating Linux and other FOSS. We consider the roles that a Linux-based OS might have in such systems; how FOSS developers, system integrators and product creators can specify these roles; and the evidence they might need to provide to support associated safety arguments.</p> <p>Use the menu on the left to navigate within the site, and the Table of contents on the right to browse within a page. Alternatively, type what you are looking for in the Search box above.</p>"},{"location":"Criteria-Documentation-Evaluation.html","title":"Criteria for Open-Source Documentation Evaluation","text":"Desirable Property Explanation Clear Documents must be unambiguously clear to the intended readers (not to anyone, just to the people active on the project) Comprehensible A document is comprehensible if the stakeholders and consumers of the document understand its meaning Detail Documents must detail complex concepts as a set of elementary measurable concepts Scale Documents must specify a scale of measure to define the concept Quantity Given a Scale, documents must specify at least two points of reference on the defined \u2018Scale\u2019 to define relative terms (e.g. \u2018higher\u2019.) These can be called \u2018benchmark\u2019 and \u2018target\u2019 in the specification. Qualify \u2018Target\u2019 must specify \u2018when\u2019 a performance level is available. Other qualifiers such as \u2018when\u2019 and \u2018if\u2019 should be explicit if not elsewhere specified. Complete A complete document is clear without further elaboration because it sufficiently describes the capability and characteristics it is intended to cover. Correct A document is correct when it is either free from error or it is accurate. Consistent A document is consistent if it contains no contradictions. Verifiable A document is verifiable if it is possible to demonstrate that all assertions in the document can be reproduced. There are no unsupported hypotheses in the document. The assertions can be verified by either demonstration, observation or review. Claims or hypotheses must be backed by references to the associated source code or published documentation (ideally in the public domain), with specific, reproducible tests to demonstrate or confirm the claim. Reproducible Reproducibility is specifically about what a document is referencing. When a document describes a project sufficiently that it can be recreated, the document is considered reproducible. Compliant A document is compliant when it is being used to satisfy a standard. The standard can be from a public source, such as IEC or ISO, or it can be a regulation as from a government, such as FMVSS. Maintainable A document is maintainable when it can be modified or extended, e.g. by the introduction of new versions or by adding/removing sections. Grammatical A document is grammatical when it is well formed. The document is in accordance with the productive rules of the grammar of a language. Because there is variation in what is expected, the grammatical rules followed for a given document should be specified before the document is created. For example, a requirements document could be specified to conform to the syntactic rules of EARS (Easy Approach to Requirement Syntax.)"},{"location":"Criteria-Documentation-Evaluation.html#file-metadata","title":"File metadata","text":"Metadata Explanation Major Version X(.0) Minor Version Example: X(.1 to .6) \u2013 Minor version can be an indicator of the maturity of the version X.1 \u2013 Initial version \ud83e\udc6a Send for peer review X.2 \u2013 Peer review feedback received \ud83e\udc6a Mark as X.2, incorporate feedback X.3 \u2013 Feedback incorporated \ud83e\udc6a Mark as X.3, send for expert review X.4 \u2013 Expert feedback received \ud83e\udc6a Mark as X.4, incorporate feedback X.5 \u2013 Feedback incorporated \ud83e\udc6a Mark as X.5, send for acceptance review X.6 \u2013 Acceptance review received \ud83e\udc6a Mark as X.6, incorporate feedback (X+1).0 \u2013 Feedback incorporated \ud83e\udc6a Mark as next Major version (.0), release ID UUID Status (See below)"},{"location":"Criteria-Documentation-Evaluation.html#status-example-only","title":"Status (Example only)","text":"Status Proposed In Progress Under Review Verified Released"},{"location":"Criteria-Documentation-Evaluation.html#file-header-metadata-example-only","title":"File header metadata (Example only)","text":"Metadata Explanation Title Title of the document Author Author of the document. Can be multiple authors. Lead Reviewer Person responsible for reviewing, gathering feedback and providing feedback to the author. Reviewers Reviewer of the document, should have relevant experience. Date Date of the current version of the document. Note that this can differ from the file date."},{"location":"Criteria-Documentation-Evaluation.html#review-ratings-example-only","title":"Review Ratings (Example only)","text":"Rating Explanation Critical Showstopper, the document is fundamentally incorrect in its current state and should be reworked. Must be fixed immediately. Severe Major problem with the document. Must be addressed or fixed before the document can be considered for further review. Minor Problem with the document, should be corrected, but review can continue. Observation Comment from the reviewer to the author about how something might be improved. Not a problem with the document. Question Could be considered as a minor also. This is a question from the reviewer to the author to elaborate or clarify something that is unclear. Could also be considered as a violation of the Clear, Comprehensible, or Detail property. Not Applicable It does not make sense to use this criterion for this evaluation."},{"location":"Criteria-Documentation-Evaluation.html#document-review-process","title":"Document review process:","text":"<p>Entry Conditions:</p> <ul> <li>An enumeration method (e.g. headings, line numbers, etc.) should be available for ease of review document feedback references.</li> <li>A mechanism should be available for tracking changes to a review document.</li> <li>Author requests the review</li> <li>Author can use the review criteria to determine if the document is mature enough to be reviewed</li> <li>The Author fills out the file metadata</li> <li>The Author fills out the file header metadata</li> <li>Review lead is selected from the approved list</li> <li>Reviewers are selected by the review lead</li> <li>Relevant documents are made available</li> <li>Perform review<ul> <li>Violations should be noted as: Critical (C), Severe (S), Minor (M), Observation (O), Question (Q), Not Applicable (N)</li> </ul> </li> <li>Mark feedback according to criteria</li> <li>Feedback should be included as comments unless the change is minor</li> <li>Feedback should be assigned to the author to address</li> <li>Note to author:<ul> <li>The reviewers are not directing their feedback at you or your ability. The purpose of this is to find potential bugs and minimize systematic error in the documentation</li> </ul> </li> </ul> <p>Exit Condition:</p> <ul> <li>Fewer remaining major defects per page than the agreed exit standard</li> <li>Recommendation is one (1) Severe (or higher) defect per page as an initial exit criterion</li> </ul>"},{"location":"Criteria-Documentation-Evaluation.html#review-checklist","title":"Review Checklist","text":"Review ID Criterion Reference Rating Comments ID_01 Is the document unambiguously clear to the target audience? Location(s) of the violation of the criterion C, S, M, O, Q, N Feedback on what the problem is and a suggested correction. ID_02 Do the stakeholders and consumers of the document understand its meaning? ID_03 Is there sufficient detail? ID_04 Are complex concepts described as quantifiable elementary concepts? ID_05 Is there a scale defined for any measurable concepts? ID_06 Are there benchmarks defined for any quantitative references? ID_07 Are there targets defined for any quantitative references? ID_08 If there are any performance ratings, does the document specify when those ratings are applicable? ID_09 Does the document sufficiently describe the capabilities and characteristics it is intended to cover? ID_10 Is the document accurate? ID_11 Is the document free from error? ID_12 Does the document contain any contradictions? ID_13 Can all of any assertions in the document be reproduced? ID_14 Are there any unsupported hypotheses in the document? ID_15 Does the document specify the project sufficiently such that it can be reproduced? ID_16 Is the document compliant with any applied standards? ID_17 Is the document organized such that it can be modified or extended? ID_18 Is the document compliant with the applicable rules of syntax or grammar? (e.g. The Trustable Software Framework rules about Statements.) <p>This work is licensed under CC BY 4.0</p>"}]}
0 commit comments