theExpeditionarium Ideas as technology.

~/../contributionGuidelines

As this work will remain open-source, its development will be public, and its contents available for copy and alteration. It is open to contribution and always in need of interested and highly motivated collaborators.

How to Contribute

The simplest means of contribution would be to correct errors or make suggestions on existing material by following the edit icons found in the top-left corner of each page. These will either bring you to a page’s source or more likely to whatever wiki-based content might be transcluded there. In the case of the former, one will encounter front matter and possibly some Liquid templating along with text written in Markdown syntax, but in the case of the latter, one should only find the text.

In many cases with the wiki material, one may notice indication of that text being a work in progress. This material is likely in need of assistance or suggestions, but it is important to keep in mind that such material is likely in active development and with some idea of its trajectory already in the mind of its author, who may or may not heed suggestions (but don’t let that deter you).

Non-wiki material has the option of either being edited directly on GitHub or with Prose.io; but unfortunately Prose.io does not recognize GitHub wiki content, and so that content can only be edited directly on GitHub if relying on the site as one’s contribution portal.

Incidentally, such reliance is by no means the recommended way of interacting with this content. The following elaborates the alternative and recommended approach.

A word on git

This work relies on git versioning, distribution, and collaboration. It is recommendable that one try git before diving into contributing in this fashion. While this might seem daunting at first, it is worth noting that interacting with git locally (rather than relying on GitHub’s own interface) has the benefit of greater portability, allowing one to work from within any preferred text editing environment. After all, authorship is like any other craft and benefits from use of appropriate tools.

Cloning

Contributing more directly is somewhat advanced: It is necessary to first fork and then clone whichever repository you wish to work on in order to submit or edit articles here. As this project makes extensive use of submodules, it is recommended that one do so in this manner:

git clone --recursive https://github.com/rapidExpedition/rapidExpedition.git

Alternatively one could do this:

git clone --recursive https://github.com/YOUR_USERNAME/YOUR_FORK.git

The former might prove the better choice, however, though it will still require some configuration of git remote, .gitmodules, and .gitignore (to ignore the changes to .gitmodules) in which the origin is changed to upstream and one’s own fork is added as origin.

A note on navigating the super-project

This project has a complex directory structure with some redundancy and many relevant submodules residing in subdirectories (_includes in the case of those wikis relevant to the site), and so it is important that first one thoroughly explores the site before attempting to make sense of the repository itself. The READMEs throughout the project’s directories should help to make some greater sense of that structure, however, and so it would be equally as important to traverse the repo on GitHub as well in order to take full advantage of the HTML-rendering of those READMEs.

Wiki-Transclusion

In attempting to edit most pages on this site, one may notice some expected content missing if attempting this from a cloned directory or from the GitHub repository, rather than from the site itself which automatically redirects to the appropriate content in most cases. In such cases where it might not, that content is likely pulled from a different source than the main body of the relevant content. For instance, a GitHub wiki’s sidebar might be pulled into a page as content (rather than as a sidebar) but not appear when editing that page’s content. This behavior is by design, and one should rest assured that if they do not know how or where to find that ancillary content, they likely have no great cause in editing that particular material. Further guidelines on this are forthcoming as the wikiTransclusion project develops.

Task Management

This project includes some task management written right into the comments in the form of TODO tasks or other task-related objects of a similar nature. These will be dispersed throughout the documentation and source of the project and can easily be addressed as such by changing a task to DOING or DONE, depending on the status of the particular task. Additionally, NOTE and IDEA can be used for less specific or ancillary task-related objects as well any other class of object one might deem necessary (care should be taken to choose well and only as absolutely necessary to keep such classes to a minimum).

This system derives from and works best with imdone and its Atom add-on in which each object is detected, cataloged, and represented as a hypertext formatted kanban card, facilitating more dynamic interaction with the object than possible from the raw text. These may link or be linked to issues on GitHub, though this implementation is currently tentative in the context of this site.

Review and Revision

This project is utilizing an experimental flow for the review and revision of all prose content. The prescribed means for making changes to completed drafts is by use of CriticMarkup.

Any text containing this markup should be committed to a designated branch with a pull-request initiated for the review of those marked up revisions. The revisions must then be accepted and rejected and committed to the branch. That process must be completed with all CriticMarkup cleared from the text before the pull-request can be accepted and its changes merged into the master branch (the branch from which the site is built and deployed).

Likewise should new posts to the blog be submitted, reviewed and revised in this fashion. An example of this process can be seen here.

Why to Contribute

This work exists for the purpose of establishing permanent and permanently evolving guidelines for the essential tasks which befall a modern citizen of the global community. It is for the development of proficiency in those tasks as well as to explore and discover just what sort of tasks might prove worthy of and conducive to a productive and proficient life. In short are we after a characterization of a complete and competent stewardship of life and civilization at large.

Written language is a well-established means of conveying ideas, and when ideas are shared and shaped collectively, they affect the development and history of the world at large. Thus, a concise and adaptive expression of ideas with substantial and universal utility could achieve a lasting and manageable legacy.