Skip to content

Commit

Permalink
documentation-reorganization (#8): Strategies for production-grade us…
Browse files Browse the repository at this point in the history 
…e of reference software
  • Loading branch information
@fititnt
fititnt committed Nov 17, 2021
1 parent 8fc0725 commit cee4b54
Showing 1 changed file with 82 additions and 55 deletions.
137 changes: 82 additions & 55 deletions docs/eng-Latn/draft-eng-Latn.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@
EticaAI, Collaborators_of <etica.of.a.ai@gmail.com>; Rocha, Emerson <rocha@ieee.org>
:toc: 1
:toclevels: 4
:sectnums:
:sectlinks:
:version-label: HXLTM Live eddition
:variable-organization-name-current: Collaborators of Etica.AI
:variable-documentation-live-link: https://hxltm.etica.ai/
:variable-python-package-manager-name: hxltm-eticaai
:variable-python-package-manager-released-version: 0.8.9rc2
Expand All @@ -13,8 +16,11 @@ EticaAI, Collaborators_of <etica.of.a.ai@gmail.com>; Rocha, Emerson <rocha@ieee.
<<<

:sectnums!:

== Preface


This book, both available online on {variable-documentation-live-link} and as an ebook,
is designed as a field guide for person's doing practical lexicography and need a kickstart on how to use HXLTM tools.

Expand All @@ -35,55 +41,15 @@ This means you can

<<<

== Getting started
== Quickstart

It's essential that you have knowledge of Arabic numerals and the Latin alphabet without the aid of computer assisted tools.
Attention to details is for such numbers and the Latin alphabet (since they often are used as part of coding systems to label lingístic content)
is much more important than knowledge of the language written in Latin script or skill to do computation with numbers themselves.

=== HXLTM reference tooling installation

Some knowledge of how to operate command line tools is helpful.
No programming skills are required.

All functionality intended for field lexicographers using HXLTM documented here either exposed as _declarative programming_ with YAML or arguments for programs should be considered a bug.

Choose at least one of the options.

==== Python package alternative

hxltm-eticaai Python package:: https://pypi.org/project/hxltm-eticaai/
Pypi, Python package manager:: https://pip.pypa.io/
Python:: https://www.python.org/

===== Active use

[subs="attributes"]
[source,bash]
----
pip install {variable-python-package-manager-name} --upgrade
----
=== Strategies for production-grade use of reference software


===== Conservative

[subs="attributes"]
[source,bash]
----
pip install {variable-python-package-manager-name}={variable-python-package-manager-released-version}
----

==== Docker alternative

#TODO: this is a draft. Will eventually be updated (2021-11-16T23:16:00Z)#

==== GitHub Action alternative

#TODO: this is a draft. Will eventually be updated (2021-11-16T23:16:00Z)#

=== Production usage

The HXLTM reference tooling is designed to be immediately production grade.
The HXLTM reference tooling is designed to be immediately production-grade.
However, if software used humanitarian usage is not challenging enough,
most softwares which advertise conformance with formats HXLTM can export/import actually have bugs.

Expand All @@ -93,7 +59,9 @@ What "backward compatibility" could we promess?
Here are some suggestions.

==== Active
If your use case is processing data right now, or what you care about is just the end result, you can use the latest versions of any tool.
If your use case is processing data right now,
or what you care about is just the end result,
you can use the latest versions of any tool.

Even if between the day you start using the tools and a new update some minor change,
it's more likely that you prefer this cutting edge approach.
Expand All @@ -102,38 +70,95 @@ it's more likely that you prefer this cutting edge approach.

In special data standards who already are not formally documented (or their documentation may be behind paywalls) they are subject to changes (which tend to be bug fixes).
The way on how to label these standards may also may also renamed over time.
Also note that even if the current maintainers,
{variable-organization-name-current},
will tend to not make changes,
like minor typographical errors for something already well documented and released on past,
we may decide to adopt fast suggestions by academic researchers without further delay.

One common industry practice would be to lock the exact command line tools version (so this would force the old ontologia file). This is still an option.
But HXLTM allows another strategy:
*a conservative approach is to get the relevant parts of the ontologia with a custom name*.
This way you have your own "custom" data standard and it's even documented on your project.
One common industry practice would be to lock the exact command line tools version
(so this would force the old ontologia file).
This is still an option and is the one documented in this book.

This approach doesn't need to happen upfront. It could be done if something changes and you prefer the old way.
===== Special case for HXLTM: ontologia files

If you think the new changes do not conform to documented standards,
please report it as a bug,
even if it allows you to revert old behavior without ask changes on code.
But HXLTM allows another strategy over the quickstart lock on version:
*a additional conservative approach is to get the relevant parts of the ontologia relevant to your case*.
This way you have your own "custom" data standard and it's even documented on your project.

This approach doesn't need to happen upfront:
if you started as _active_ user and then something changed,
it is possible to copy only the ontologia files of older versions.

==== Archival
The "archival" behavior is likely to be the one used for either academic researchers,
librarians or higher levels of compliance (like use HXLTM to explain some custom format).
The difference in this approach is when just freezing the exact command line tools version is not sufficient.
The difference in this approach is when just freezing the exact command line tools version _is not sufficient_.
Your use case cannot be sure if you need the exact versions for more than 3 years or 30 years, maybe much more.

The HXLTM reference tools are public domain.
While at time of code writing most PEP8 code conventions were followed,
While at time of code writing most code style guides were followed,
the maximum lines per file was not,
so less, much less files and no bureaucracy.
Even the characters per line are capped at 80 columns,
so it would fit on paper.
These types of decisions are simpler if you want to archive everything as part of your work.

While this strategy suggestion may resemble how software like Apollo 11 was reconstructed via code printed on books,
While this strategy suggestion may resemble how software like
https://github.com/chrislgarry/Apollo-11[Apollo 11 guidance computer (AGC) via code printed on books],
note that the average lexicographer would somewhat work with old dictionaries.
Most content from public dictionaries we have today we're extracted from century-old books.
Also, the very idea of ontologia files is one way to explain how one code convention is related to another.

This approach makes the way HXLTM is explained on the ontologia an acceptable trade off between adding new features and allowing such level of archival.

=== HXLTM reference tooling installation

Some knowledge of how to operate command line tools is helpful.
No programming skills are required.

All functionality intended for field lexicographers using HXLTM documented here either exposed as _declarative programming_ with YAML or arguments for programs should be considered a bug.

Choose *one* of the options.

==== Python package alternative

[NOTE]
.Quick external links for this topic
====
[horizontal]
{variable-python-package-manager-name} Python package:: https://pypi.org/project/{variable-python-package-manager-name}/
Pypi, Python package manager:: https://pip.pypa.io/
Python:: https://www.python.org/
====


===== Active use

[subs="attributes"]
[source,bash]
----
pip install {variable-python-package-manager-name} --upgrade
----


===== Conservative

[subs="attributes"]
[source,bash]
----
pip install {variable-python-package-manager-name}={variable-python-package-manager-released-version}
----

==== Docker alternative

#TODO: this is a draft. Will eventually be updated (2021-11-16T23:16:00Z)#

==== GitHub Action alternative

#TODO: this is a draft. Will eventually be updated (2021-11-16T23:16:00Z)#


[#HXLTM-TLDR]
=== TL;DR: Too Long; Didn't read

Expand All @@ -157,6 +182,8 @@ include::../bin/hxltmdexml.py[tag=epilogum]

<<<

:sectnums:

== Introduction
:sectnums:

Expand Down

0 comments on commit cee4b54

Please sign in to comment.