This work enters the commons based on real experience and an sincere willingness to share. We hope that there will be many authors over time and that they will make sharing ever easier. Here several downstream technologists offer their advice on how to make the work more meaningful to a broader audience.
This work has its genesis in a singular event. This becomes our template. But from here on out authors are welcome to speak of "we" without being all that sure who we are. Our readers will be aware that there are more than one voice here. Avoid the desire to be too specific. We write as a community united.
We resist referencing content that cannot become part of this commons due to incompatible license, format or retention. Citations should reference works that can be included with our paragraphs in this repository. We accept markdown linking conventions and well known web formats that can be near universally rendered and reused.
We expect our words to be read in a variety of formats. We author in github flavored markdown because the format is easily interpreted and the company supports open works as our own. Various reformulations will reach a broader audience and we happily accommodate their specific authoring needs.
- GitHub flavored markdown.
- Read the Docs by natural import.
- Federated Wiki by mechanical translation.
- Ebook formats to be determined.
Here experts in the various formats describe writing conventions that will make best use of their mediums. We hope to meet all requirements simultaneously by a single document. We may make some exceptions but each levies a tax of distraction taking mental cycles from producing the best product.
Cited works should be included in the repository and cited as such with a relative link and default protocol. This requires shared be checked into this repo and addressed with addresses that begin with a single slash (/}.
Our tooling is having issues with the multiple H1's as we generate TOC’s from the headers.
(explain the ideal here.)
This wiki expects document sections and subsections to stand alone as citable and quotable advice. We expect both # and ## titles to describe their content concisely and free of context outside of general engineering terminology. Both top-level sections are expected to begin with a shore paragraph defining the content within. We expect these paragraphs, the synopsis for sections, to read well when transcluded into the table of contents.
(to be determined)
We expect users of this material to have many of their own experiences that are valuable and worth sharing in their own right Individual communities will write to their own audiences. When this writing becomes recognizingly important we ask that it be generalized to fit a broader audience. The GitHub markdown and GitHub pull request formalisms will remain the preferred update process independent of downstream format.
We further expect downstreams to follow at least major revisions and have timely releases in their own preferred format. Effective automation will simplify this so long as all authors consider the various constraints mentioned above.
We are also happy to hear of successes and/or improvements independent of revisions to this work.
Keep in touch.