Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite documentation #971

Merged
merged 56 commits into from
Dec 6, 2022
Merged

Rewrite documentation #971

merged 56 commits into from
Dec 6, 2022

Conversation

MattiSG
Copy link
Member

@MattiSG MattiSG commented Dec 1, 2022

The README of this repository was initially created as a the first public presence of Open Terms Archive, before a website was even created. It contains a mix of political statements, user documentation and technical documentation, and is overall obsolete. Beyond outdated contents, the growth of the ecosystem, the maturity of the website and the architectural choices of moving slowly from a monolithic system to a more modular approach to keep the code maintainable, all mean that the documentation should now be focused on the technical aspects of the engine, and the user documentation kept separate.

This changeset:

  • Rewrites the entirety of the README to remove outdated information and focus it on the technical aspects of the engine.
  • Creates a docs folder containing user documentation, that will be at some point moved to the recently created OpenTermsArchive/docs. This documentation is consolidated from different parts of this repository and other relevant repositories,
  • Removes the outdated French translation of the user documentation parts of the README.

If merged, the following subsequent actions should be taken:

  • Remove the documentation from contrib-declarations.
  • Update links to the documentation in each collection README.

Co-authored with @Ndpnt.

Fixes #811 #963.

Relates to OpenTermsArchive/contrib-declarations#696 (comment)

Depends on OpenTermsArchive/contrib-declarations#746.

Copy link
Member

@clementbiron clementbiron left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have some feedback but nothing blocking, well done!

@@ -12,7 +12,7 @@ First of all, thanks for taking the time to contribute! 🎉👍
- [Practices](#practices)
- [Errors handling](#errors-handling)

---
- - -
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't really matter but I'm curious to know what is the reason for this change in the format of <hr />?

As a reminder, markdown files will be linted when they are migrated to the docs repository, and the following rule will apply: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md035---horizontal-rule-style

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally prefer using the style with spaces for horizontal ruler, because it is unambiguous with the underline title style:

This is not a title.

---
This is under a ruler.

is less clear to me than

This is not a title.

- - -
This is under a ruler.

and in case of a forgotten whitespace, this will still render as a ruler:

This is not a title.
- - -
This is under a ruler.

whereas this won't:

This is not a title (but is rendered as such)
---
This is under a ruler.

As for rule MD035, we can define the string to whatever we want, so if you agree with my point of view we could very well define it to - - - 🙂

README.md Outdated Show resolved Hide resolved
README.md Outdated Show resolved Hide resolved
README.md Show resolved Hide resolved
README.md Show resolved Hide resolved
docs/doc-contributing-documents.md Show resolved Hide resolved
@@ -0,0 +1,22 @@
# Governance
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not simplify the naming of the file by governance.md ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs/guidelines-declaring.md Outdated Show resolved Hide resolved
@@ -0,0 +1,21 @@
# How to explore a history of versions
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why the file is named howto-... and not how-to-... ? (it may be that my English is not good enough)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As explained in #971 (comment), the idea was to have categories as prefixes, thus making them stand in a single “namespace” of sorts. I agree this could be improved.

scripts/dataset/README.md Show resolved Hide resolved
MattiSG and others added 9 commits December 6, 2022 12:09
Co-authored-by: Clément Biron <clement.biron@gmail.com>
Co-authored-by: Clément Biron <clement@opentermsarchive.org>
Co-authored-by: Clément Biron <clement@opentermsarchive.org>
Do not do it in the codebase, API and CLI yet as it would trigger a major and this branch is focused on rewriting documentation
Add example to remove property
@MattiSG
Copy link
Member Author

MattiSG commented Dec 6, 2022

@Ndpnt I renamed “document type” to “terms type” everywhere except in code in 9049cd3, please let me know if you'd prefer that we delay this and have a single changeset with codebase, CLI, API and documentation as part of implementing #964.

@MattiSG MattiSG merged commit 40687db into main Dec 6, 2022
@MattiSG MattiSG deleted the docs branch December 6, 2022 16:10
MattiSG added a commit to OpenTermsArchive/opentermsarchive.org that referenced this pull request Mar 6, 2023
Ndpnt pushed a commit to OpenTermsArchive/opentermsarchive.org that referenced this pull request Mar 6, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Document instances multiplicity
3 participants