Comments (1)
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.
from alan-i18n.
Related Issues (14)
- Adopt New Official Extensions for ALAN3 Solution and Transcript Files
- Fix Travis Badge Link
- Add MESSAGEs Template
- Help with Swedish MESSAGEs Template HOT 2
- Dubious Code in 'take.i' HOT 1
- HELP — Spanish Speaker Needed! HOT 4
- Untranslated Spanish Messages
- Wrapping Bug for Spanish GNA HOT 2
- Spanish BUG: Syntaxes with "de" Not Working! HOT 10
- Spanish Lib 0.3.3 Tasks List HOT 6
- Lib EN: 'brief' and 'verbose' not Meta Verbs HOT 2
- Spanish Foundation v0.4.0 HOT 5
- Lib EN: Add Cloak of Darkness
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from alan-i18n.