Documentation lacks a lot of intros for new devs etc.

[ciampix]

It's missing an introduction to devs or wannebe: 1) the "why the project" ... I discovered of this article: https://dev.to/kantord/why-i-built-librelingo-280o via matrix... well at least put a link in the docs 2) which technology was used and why 3) Starting point to the development tools used (links to help new developers or wannabes become used to the tools / languages / libraries / etc.) 4) examples 5) low hanging fruits 6) how and why and who should contribute to the docs themselves (why this is paramount for an healthy project in itself is left as an exercise ;-)

etc...

to sum up: it's missing an important part of the docs: everything that could help to help the project. I think this is the most important function of docs in general.

[kantord]

Thanks @ciampix

@allcontributors please add @ciampix for bug

[allcontributors[bot]]

@kantord

I've put up a pull request to add @ciampix! :tada:

[kantord]

As per:

the "why the project" ... I discovered of this article: https://dev.to/kantord/why-i-built-librelingo-280o via matrix... well at least put a link in the docs

I tackled that in this MR today: https://github.com/kantord/LibreLingo/pull/953

So I think it shouldnt' be an issue anymore :-)

[kantord]

low hanging fruits

What do you exactly mean by that, @ciampix? Issues that would be easy to resolve?

[kantord]

how and why and who should contribute to the docs themselves (why this is paramount for an healthy project in itself is left as an exercise ;-)

This should be probably a required part of code reviews, right? I also wonder if there are some automated ways of making sure that the docs don't get outdated? :thinking:

[ciampix]

low hanging fruits

What do you exactly mean by that, @ciampix? Issues that would be easy to resolve?

Exactly!

[ciampix]

how and why and who should contribute to the docs themselves (why this is paramount for an healthy project in itself is left as an exercise ;-)

This should be probably a required part of code reviews, right? I also wonder if there are some automated ways of making sure that the docs don't get outdated? thinking

There are two types of docs generally: code/dev docs and user docs. The best place for code/dev docs is inside code itself so code is auto-documented (as it is with Python, Perl, Java etc. all these high level languages define some kind of embedded documentation directives - see Pods for Perl, autodocs for Python etc.). Instead user docs are meant for users. These docs should: 1) follow the same versioning that use the program to assure that they are referencing to the right behavior 2) be written in a high level light markup language like md, rest or asciidoc (my preference are in the reverse order) 3) be translatable with some external tool like sphinx for rest or po4a for md or aciidoc feel free to ask me how to implement asciidoc(tor) + po4a for handling automated translation support for docs

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.