Write a proper documentation + produce a video on 101repo

[rlaemmel]

The following text is LEGACY.

It is just preserved here for the moment when this issue is resolved.

=== Implementations folder ===

All implementations are hosted by the implementations folder.

There is one folder per implementation.

==== Id ====

Each implementation has a unique id which serves as the folder name.

Here are guidelines for the id:

• The id should be pleasant to read because it may appear in the text of wiki-based or other documentation.
• The id should also avoid any sort of clashes with concepts or technologies of 101companies.
• The id should use [http://en.wikipedia.org/wiki/CamelCase camel case] unless this is a hardship for a particular implementation.

For instance, "java" is not a valid id because "Java" (don't mind capitalization) is needed as the name of a programming technology.

==== README ====

Each implementation must have a README file directly within the implementation's folder.

A detailed [[101companies:README|specification of the READMEs]] in terms of document structure and conventions is available.

==== Dependencies ====

Each implementation may have '''relative''' dependencies to other implementations (i.e., subfolders of the implementations folder) and technologies (i.e., subfolders of the technologies folder). That is, the idea is that implementations can be "checked out" and built and executed anywhere in a file system of a user as long as the folder hierarchy is preserved and all dependencies are checked out together with the implementation of interest (also assuming that all other prerequisites are satisfied). The README file of an implementation must identify dependencies of that kind.

==== Pseudo implementations ====

It may happen that several implementations would like to share some parts of an implementation. For instance, it may be that several implementations share the objective of demonstrating a particular database technology, and they even agree on the relational schema. In this case, we may designated an extra implementation (say, a "pseudo implementation") to hold on the shared part. We call this a pseudo implementation because incompleteness with regard to the 101companies scenarios is severe but expected. Without pseudo implementations, we would need to clone more, or common parts would need to be placed, so to say asymmetrically, in one specific implementation which are however is not fully reused by the other implementations. Another context that may suggest such a pseudo implementation is the use of XML technology where several implementations could agree on the same XML files for data and the same XML schemas.

=== Technologies folder ===

For convenience's sake, technologies may be redistributed via this folder.

Also, designated documentation for technologies may be hosted in this folder.

==== Redistribution ====

Whether or not to redistribute a technology is a pragmatic decision, but license issues may also play a role. Redistribution may speed up users in running implementations.

==== Documentation ====

Whether or not to provide 101companies-specific documentation in the technologies folder depends on the chosen documentation model for the 101companies software corpus. If technology documentation is file-based and web content is generated by tools, then the documentation files are to be collected in the technologies folder. If instead documentation is wiki-based, then the documentation files are perhaps not needed, or they may be extracted regularly from the wiki.

=== Concepts folder ===

Whether or not to provide a concept folder depends on the chosen documentation model for the 101companies software corpus. If concept documentation is file-based and web content is generated by tools, then the documentation files are to be collected in the concepts folder. If instead documentation is wiki-based, then the documentation files are perhaps not needed, or they may be extracted regularly from the wiki.

=== Tools folder ===

All tools for the management of the 101companies software corpus are maintained in the tools folder. The assumption is here that some developers of 101companies implementations may need to apply or even adapt these tools, and hence they should be provided with ease of access. These tools and their usage are to be described elsewhere (eventually).

[avaranovich]

@rlaemmel Need to discuss and validate a new submission process. We have a bunch of to-be-committed Android implementations -- a nice test case.