10

Ideally, like @Andrew - OpenGeoCode mentions, you would release it in multiple formats. I would really suggest you look into organizing it into a e-book written in Markdown and hosted on Github. There are several advantages to this such as a built-in change log, being able to let people to (publicly) fork your document(s) and share their changes with the ...


6

The other suggestions on here are great, and I would echo the recommendation to consider Github if you want people to be able to easily edit your product for creating their own versions. This will also help you track the edits that have been made so you can learn more about what people do with your manuals. If you want to learn more about the definitions ...


4

I don't know that there can be a good standard other than what I was taught when studying environmental computer models, which is to be clear about everything up-front. Obviously this has to be documented somewhere in the expected place (like a README or the like) but the following things should probably be addressed on some way: Methodology of how the data ...


3

Do you know specifically who will be editing your manual or you plan to open them and see what happen? If you already have contact with potential editor and contributor, just ask them what makes sense to them. Markdown and Github is a great option if you community knows how to use them.


3

From dataset documentation in Table IV of Harrison & Rubin (1978), LSTAT is defined as: Proportion of population that is lower status = 1/2 (proportion of adults without, some high school education and proportion of male workers classified as laborers). The logarithmic specification implies that socioeconomic status distinctions mean more in the ...


3

Code generation is often considered to be an anti-pattern for REST APIs: the goal is to allow clients and servers to evolve independently as much as possible. Generating client code from a WADL document, as you might do from SOAP, will make the client brittle to server-side changes. It'd be better to "bootstrap" the client by consuming the WADL at run-time ...


3

There's a proposal called 'Linked CSV' which allows you to subtly insert bits to a CSV file so that it is simply transformed into RDF. Documentation here - see in particular '2.2.4 Self Description' The benefit over YAML is that it is still proper CSV, so will be read & written easily by the same tools as normal. The benefit over the likes of Data ...


2

YAML frontmatter tends to be the generic standard for documenting text files. Parseable/compatible with JSON, easily human readable, easy to type in. It's used in content management systems, in combination with Markdown, to append metadata to blog posts in text files without the need for fully blown content management systems. http://www.yaml.org/


2

Have you looked at Apache AVRO (http://avro.apache.org/)? Avro relies on schemas. When Avro data is read, the schema used when writing it is always present. This permits each datum to be written with no per-value overheads, making serialization both fast and small. This also facilitates use with dynamic, scripting languages, since data, together with its ...


2

I think the key is to that the data gathering and usage document should be pretty heavily integrated. This really should be documented as part of intended use and use caveats. In other words, documenting data sampling methods and assumptions, and problems gathering or releasing the data is what is needed, and gaps in data are just a part of that picture. ...


2

I do not know of standards in this area, but I do know that many data owners document missing data or other known issues in a dataset. This is generally documented in either the site from which the dataset is linked or in the metadata of the dataset itself.


2

In the old data.gov metadata schema, statistical datasets were required to supply a bunch of additional metadata that disclosed the following items: Statistical methodology Sampling Estimation Weighting Disclosure avoidance Questionnaire design Series breaks Non-response adjustment Seasonal adjustment Data quality (variances, CVs, CIs, etc) This would ...


2

Those are pretty common terms for building permits. "New construction" means that they're building (or placing) a new building. "renovation/alteration" means that there's an existing building that's being modified. What qualifies as a renovation can get a little interesting by area ... I remember one of my co-workers telling me that in Virginia if you ...


2

Just another view on this. I've been working in and around REST and RESTful APIs for a while, sometime going deep down the Hypermedia api sometimes not. With a hypermedia based API the intention is not to have many documented endpoints into the API but a small number of or even single endpoint from which the client can walk the API to find what they are ...


2

I haven't looked at WADL in detail, but I think that if you want a fully described service, SOAP may be the right thing in the first place? The success of RESTful services can, I believe, in large part be attributed to their lack of formalism. An interface that emits and consumes JSON can be made somewhat self-explanatory through the use of URIs for entity ...


2

USAID is in the process of finalizing its geospatial data standards, which we expect to make available in 2017. As stated in our Frequently Asked Questions (FAQs), datasets must be submitted to the DDL "in a machine-readable, non-proprietary format." As a matter of practice, the DDL will accept proprietary formats as long as the submitter also provides a ...


2

MediaWiki is a good alternative in getting your documentation out to the public without requiring knowledge of GitHub. There are some Extensions to link to GitHub, noteably The GitHub Extension allows to embed files from GitHub. This GitHub Template provides a convenient way of linking to mediawiki source files hosted in the github mirror


2

I'm not an expert on this specific subject matter, but I think the helpful 2017 AHS Definitions.pdf (found on page Definitions, Accuracy, Historical Changes, and Questionnaires) clarifies this topic. On page 18 it states: Housing units. A housing unit is a house, apartment, group of rooms, or single room occupied or intended for occupancy as separate ...


1

Draft geospatial standards are now posted for comment / feedback at www.usaid.gov/data.


1

if you set your baseline as JSON, conversion to all of the formats listed is trivial, and can be easily automated. not listed, and perhaps relevant here is JSON-LD, although i'm not very familiar with it, so that could be wrong: definitely worth a look into.... emphasis: publish html so that its indexed and searchable on the web; moreover, if you use web ...


1

I think the answers here are pretty comprehensive, but I am not sure how complex the documents that are being produced. Sometimes, Markdown isn't robust enough to support advanced documents (e.g., footnotes, bibliographies, etc.) I would also recommend looking at Pandoc or Multimarkdown. It won't necessarily render in GitHub, but is a good way to keep a "...


1

In RDF, you can do the trick mixing these ingredients: an observation ontology or vocabulary; RDF blank nodes; a provenance ontology. Sensor and Observations Ontologies There are many ontologies for measurements and observations, see e. g. this (outdated) list. In the example below, I will use quick and dirty ad-hoc vocabulary, do not take it seriously. ...


1

going out on a limb here, but GitHub recently published a guide for citing Open Science data that sounds very similar to what you are seeking, including the desired audience, except i don't see anything about plain text, and since i'm only helping out here, i did not try the demo. Digital Object Identifiers (DOI)s are used here in place of the plain text ...


1

As obvious it is complex to have both data and metadata in the same file while keeping the structure simple. For sure XML can help a lot, but as far as I know there is no unique standard for the metainformation. What could help you in some ways could be RDF (in one of its many formats)... It's a long shot and it depends on what your scientists have to do ...


Only top voted, non community-wiki answers of a minimum length are eligible