cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrey Kurdumov <kant2...@googlemail.com>
Subject Re: Documentation generation process
Date Fri, 30 May 2014 08:06:24 GMT
Yes, you are right, I overlook that wiki page.

3. When I talk about CONTRIBUTING.md, I mean
https://github.com/apache/cordova-docs/blob/master/STYLESHEET.md which has
a lot of good suggestions for document writers. But same rules should be
translated and applied by translators too, and would be good if
recommendations for them would be written on the language to which we will
translate too. That should help maintain stylistic consistency across
documentation and translations. I think about cases when people read
documentation on their native language and see that that docs could be
improved and read about ways to improve by writing article or fix
translation and read instructions for that on their native langauge, and
not on English. What do you think?

1. and 2 looks like resolved.

4. Still interesting to know how Hastings goes, does it still alive or not?
5. I thought about putting links in the docs, but they should have
reference across .md files, over wise translators have to know how names
for HTML files are generated, which is bad and we move problem from one
place to another IMO. Any change in this direction looks like we going from
joDoc to other documentation generation tool and that should be discussed
with more wider audience.
6. I think that would be good to have some verification script which will
count of automatic links in English version against target language,
Russian in this case. That at least allow verify that some part of
translations are broken and know where it is broken. I think about Crowdin
first, verify second approach. Redownloading Crowding content each time
when page is translated for verification does not looks fun.
7. Any way we could make code on the wiki page which you give to me
collapsible, it not that important when reading documentation, but It make
document look big. I only glance over it and that's why I re-raise
questions which was solved earlier again. Sorry for that.



2014-05-29 0:04 GMT+06:00 Lisa Seacat DeLuca <ldeluca@us.ibm.com>:

> Andrey~
>
> The information on the translation process is available on our wiki here:
> http://wiki.apache.org/cordova/CordovaTranslations.  It'd be nice if we
> had additional information somewhere to get people's attention before they
> start translating.  I'm open to suggestions on where to put the details.
>  The crowdin site doesn't allow me to have a "readme" type of file.
>
> The reason the links as broken (as talked about in the wiki) is because
> the translations do not match between the headers on different pages.  For
> example, one might say "hi" and the other says "hello".  They mean the same
> thing but because the characters aren't EXACT, the link is broken.  When
> they appear black that is the cause.  It's a very manual and frustrating
> process to have to go and compare the broken link translations and make
> sure they match for each language and every link.  I believe this is just a
> shortcoming of using markdown.  We could probably put in a bunch of
> hardcoded links but that'll take some work on our part to get the docs all
> setup.  It's a good suggestion though, I'm all for making it easier on
> translators/me.
>
>
> Lisa
>
> Lisa Seacat DeLuca
> Mobile Engineer | t: +415.787.4589 | *ldeluca@apache.org*
> <ldeluca@apache.org> | | *ldeluca@us.ibm.com* <ldeluca@us.ibm.com> |
> *lisaseacat.com* <http://www.lisaseacat.com/> | [image: follow
> @LisaSeacat on twitter] <http://www.twitter.com/LisaSeacat>| [image:
> follow Lisa Seacat DeLuca on linkedin]
> <http://www.linkedin.com/in/lisaseacat>
>
>
>
>
>
> From:        Andrey Kurdumov <kant2002@googlemail.com>
> To:        dev@cordova.apache.org
> Date:        05/26/2014 05:01 AM
> Subject:        Documentation generation process
> ------------------------------
>
>
>
> Hi guys,
>
> I start verifying how my translation to Russian look at the actual site and
> found that sometimes
> links does not displayed on the same place where they are in English docs.
>
> Initially I start from
> http://cordova.apache.org/docs/ru/edge/guide_platforms_index.md.html
> where almost all links are broken.
> I check Italian and French translation, almost all link are in place, so I
> made assumption that
> this is probably something wrong with my translation and go to the Github
> to look at actual .md files.
>
> https://raw.githubusercontent.com/apache/cordova-docs/master/docs/en/3.4.0/guide/platforms/index.md
>
> https://raw.githubusercontent.com/apache/cordova-docs/master/docs/ru/3.4.0/guide/platforms/index.md
> I find that no actual links are in the Markdown files. So I assume that
> some magic in generator is
> injecting links. I start looking at the cordova-docs/lib folder and don't
> find anything.
> I look and joDoc and find that there some function which look across all H1
> in all files and
> use that H1 as link targets in the docs.
>
> This is raises following questions in my head:
> 1. Does I correctly find root cause for broken links in the docs? Could
> somebody with more knowledge about docs
> generation confirm that and give more details about how this working,
> because I may miss some other things.
> 2. Could we put information for translators how links are generated. That
> way they will know that
> all references to other sections should be in the same grammatical case as
> name of the section.
> That should be strict rule for transaltors, since it could make content
> orphaned. Also not technical
> translators could fix such issue themselves.
> 3. Could we put cordova-docs/CONTRIBUTING.md in the docs foder, so it could
> be translated for other languages.
> Also that file could be separated on stylistical rules, which probably
> would be universal across all languages,
> and language specific grammar rules and common grammar/orthographical
> mistakes which people made.
>
> There are more broader question:
> 4. Do the need such simple system for linking, which could be easily broken
> when we have 2 files with same H1 content
> For example would be not uncommon to have sections like 'Overview',
> 'Upgrading' and so on to appear in multiple areas,
> like in multiple plugins.
> For example:
>
> http://cordova.apache.org/docs/en/edge/guide_platforms_ios_config.md.htmland
> this was recorded as
> CB-5464 (as of 3.1 release).
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message