tajmone
commented
3 years ago So, currently both the English and Swedish contain a lot of background info about the history, ancestry and recovery of this library (which was in English only).
That information seems like it should be consilidated on the top level.
The language-level Readme should probably focus on information on that library itself, possibly referring to the top-level README.
I agree, and I did something similar for the CHANGELOG files, where I moved all the version info into a shared top level document.
The reason I left some of that redundant info (i.e. even after revising the Libs' READMEs) was that each non-English library will most likely end up having also a README in its own language, so I thought the English text might work as a sort of baseline for the translation — i.e. thinking of the final distribution package of each separate library, each package should contain that base info in its own READMEs (EN + whatever locale).
Once we switch to using AsciiDoc for all documentation (and READMEs too), we'll probably end up having a source folder for all docs and generate them via include::[] directives, so redundant info won't mean duplicate sources maintenance.
The only obstacle in this is that GitHub doesn't support include::[] directives in its web previews of ADoc docs, so if we want to use ADoc also for READMS docs we'd have to generated them via the AsciiDoc coalescer. This make things harder in a way, but also easier in some other respects: editing a single doc might require editing multiple sources, but changing some common snippets will only require editing a single file and will have effect on all docs (e.g. bumping up the attribute defining the current ALAN SDK version).
But your suggestion is the best way to go right now, i.e. let's begin by:
- moving redundant info into a single markdown doc in the repo root, and just link it from the Libs' README.
- keep in each Lib's README only the essential info that its unique to that lib (e.g. in Lib ES its roots in the pALANte lib, its authors, etc.).
But maybe, before doing so, should we create a copy of these library README.md files as they are, renaming them as README_<locale>.md, so that it would make their translation easier? E.g. for the Spanish lib, just keep a copy named as README_ES.md, so that when we find a collaborator fluent in Spanish he/she could simply translate it to Spanish "in place", without having to go hunting for info snippets in other docs (i.e. that file is all that needs to be translated).
We should consider all these markdown README docs as targeting devlopers, not end users of the libraries. In the final distro packages, we'll be adding an HTML document created ad hoc, via Asciidoctor, which will include all the necessary historical info (as mentioned above, by collating together various ADoc sources via include directives). But of course this only applies to English documents, not to locale specific docs.
We just need to ensure that during the consolidation process no important info is lost along the way, since we'll be needing it in the ADoc source folders.
I started the Swedish library by copying the English. This gives a good starting point, but also a lot of duplicated documentation.
So, currently both the English and Swedish contain a lot of background info about the history, ancestry and recovery of this library (which was in English only).
That information seems like it should be consilidated on the top level.
The language-level Readme should probably focus on information on that library itself, possibly referring to the top-level README.