Bug#959006: [live-manual] translation/contributing documentation inadequacies
Package: live-manual
Version: 2:20151217.1
In moving (in live-manual MR #27) the contributing notes out of the
manual itself to files under `doc/` in the repo, I see problems with
the translation/contributing documentation that could do with
addressing. Preferably after MR #27 has merged.
I'd submit an MR myself, and may do later, but now's not the best
moment to do any such rewriting for me (more important stuff to
address) and I'd have to research the translation tool usage details.
Including:
- The set of files referenced for starting a new translation seem to
be outdated and in need of replacement with reference to all *.pot
files.
- The instructions should be reclarified to instruct making a copy of
the *.pot files as *.po files within manual/po/XX/ where XX is a
suitable language reference, and then translate those files.
- The *.pot files can commonly be out of date, making it a good idea
for translators to start by regenerating them to ensure they are
working from up-to-date strings. There are no instructions about this.
It may be also be helpful to give a hint as to whether or not a commit
updating the *.pot files is welcome.
- Similarly there could be stray *.pot files (or stray translation
*.po files) left over from removed English files, so a good idea to
hint that they compare to the set of English *.po files to ensure they
do not unintentionally waste time.
- The `doc/contributing.md` content should perhaps note to readers
that they should checkout `doc/authoring` for SiSU markup hints (until
such time that we possibly move to a more common markup if we do).
- The new `doc/contributing.md` file (which is focussed on
contributing to the manual) should be adjusted to properly suit the
different users who might read it - those wanting to update the English
text vs. those interested in translating.
Reply to: