This repository contains documents that can be used freely and openly in software development projects. These documents are mainly guidelines and recommendations and can be used as local recommendations, regulations, or samples. The documents can be applied as a whole or as a derivative document controlled by the document license (see below).
The documents are like
-
formatting guides
-
pull request guidelines and other documents.
The license of this document is CC BY 4.0, as defined in
The individual documents should define their own licenses.
The recommended license of the documents is usually CC BY 4.0, as defined in
|
Note
|
The rationale behind requiring that the individual documents define the license themselves is that they may be copied or moved. That way, they may lose the link to the source. At the same time, the license information is essential and should be unambiguous. |
For shorter documents, we can use Markdown. For longer documents, the suggested format is Asciidoc. Asciidoc is usually preferred over Markdown.
Some documents may contain placeholders. Such placeholders are used to ease the document modification for a specific use. For example, the document is a regulation companies can use daily. In that case, the original document can contain some made-up name. Another approach is that the document contains a placeholder in the place of the made-up name. That way, it is easier and less error-prone to process the document and replace all occurrences of the placeholder with the specific organization or company name.
The suggested format is to use {% and %}, separating the placeholder from standard text.
|
Tip
|
As an example, a document may contain an organization name. Then the text will contain {%company%}.
When Acme Corp. implements the document as their own, they can easily replace the strings {%company%} with Acme Corp.
|
It is also recommended to name those files as adoc.jam and use the Jamal tool to process the documents.
The language of the documents is English. The majority of the developers are not native English; thus, it is not enough the text is proper English. It has to be simple.
It still has to be defined. Ideas are welcome. Perhaps the documents should contain their version themselves, and there must be a git tag for finalized versions. I envision semantic versioning, but the original levels, such as Major, minor, and patch, should have different meanings. After all, these are documents with content and not libraries with APIs.
Also, the tagging in git is not trivial because, in git, the repository state is tagged; the repository has a version and not the individual files.
Suppose a contemporary and continuously maintained document on the net with the same or similar license about a specific topic exists. In that case, there is no reason to duplicate the work. In such a case, we may have a document that describes the available other resources with recommendations.
For example, the JPL Java coding standard is an outstanding document available at http://lars-lab.jpl.nasa.gov/jpl-java-standard.pdf, and it should not be created again. Even though it currently seems to be outdated.
As I started this project, I did not imagine it as a one-person show. I will try to create meaningful documents as a starting point, but anyone is welcome to participate.
You can and are encouraged to
-
fork the repository, make corrections, additions and create a pull request,
-
create issues and comment issues. Issues can cover topics related to the whole project, project governance, or a specific document. You are welcome to ask and answer questions on issues. You are welcome to express your opinion on issues,
-
comment on pull requests and issues.
All communication and documentation work MUST follow the guidelines outlined in the document Code of Conduct.
This project will never be in a final state. It will be either in progress or abandoned, deprecated and dead. It is how projects are and, more generally, life is.
There are documents in this project space that are not document templates. These are
-
this
README.adocin this file -
CODE_OF_CONDUCT.adocis a standard code of conduct description -
CONTRIBUTING.adocdescribes how to contribute to this project -
EXTERNAL_DOCUMENTS.adoclists external documents and resources that serve similar purposes and are not replicated here
Every other document is part of the open document set.