Re: [darktable-dev] Re: Introducing dtdocs
On 10/19/20 12:12 AM, juli...@i2pmail.org wrote: There's a saying, "Sorry I didn't have time to write less." :) Indeed that is true! Glad you see the need. About the choice between Hugo or Jekyll, The choice is Hugo, Jekyll was not a consideration. I realize that some may like the speed of Hugo, but Jekyll does have incremental builds (I read that Hugo doesn't have that). In my experience working on sites with thousands of pages, by using the incremental build tag and limiting the number of languages on my local end, I would have a site I can re-test in a second or two. Jekyll needs incremental builds because ruby is slow as hell. If you want to take a look at some benchmarks: https://forestry.io/blog/hugo-vs-jekyll-benchmark/ Hugo doesn't need incremental builds, because it is fast. Hugo is written in Go also. That might be obvious from the name, Hu"go", but it probably isn't to most. So I suppose those who might want to do the documentation would need to access whether they want to use a Go binary over Ruby. The Go binary is way easier. You can download the binary directly from the hugo project, it has almost everything you need. The only other dependency is yarn to grab some NPM packages. I started on Jekyll, then moved to middleman becaue Jekyll focused too much on blogging, then eventually to Hugo when ruby proved to be too brittle and too much upkeep. You can observe a similar problem with python and the darktable.org website, which still uses pelican from python 2.7. -mica J On 2020-10-19 02:44 UTC Mica Semrick wrote: Hey Torsten, Minimalism is a basic tenant of technical writing. We should strive to convey the "thing" in question using the fewest words and image to (1) reduce the maintenance overhead and (2) more words/images generally do not make the "thing" clearer, in fact, quite the opposite. It often muddies the picture. The current documentation has a colloquial verbosity to it that (I feel) doesn't enhance the understanding of the reader. Similarly, there are images that don't enhance the readers understand either, for instance in the current documentation there is a image of every since module just ahead of the textual description of that module. In the new docs, we've split out module references into their own section and we assume you have darktable open in front of you (or you know what a module generally looks like) and thus we omit the image. If there are specific instances where you think not enough is written, you are encouraged to open an issue. Hope that makes sense. Hey Torsten, Minimalism is a basic tenant of technical writing. We should strive to convey the "thing" in question using the fewest words and image to (1) reduce the maintenance overhead and (2) more words/images generally do not make the "thing" clearer, in fact, quite the opposite. It often muddies the picture. The current documentation has a colloquial verbosity to it that (I feel) doesn't enhance the understanding of the reader. Similarly, there are images that don't enha ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
Hi Jeronimo, Thank you for your all your work; last I had looked br_PT was the most up-to-date. We haven't really defined exactly what the translation workflow will look like, but if we get feedback from translators that they still want to work with PO files, I know we can certainly accommodate that. Weblate can do nice things like use and keep a translation memory, leverage machine translation, and who knows what else; I haven't had time to fully dive into it yet. I am not aware of what emacs can do. I think a decent portion of the manual would need to be retranslated, as a good chunk of it has been rewritten. As I mentioned previously, I can make translation memories from the current PO files and import them into weblate or make them available to you via some other means. Since there are a lot of new writings, I don't think that the old translations will match up very well. I'm open to exploring machine translation for a first pass if you'd like to do that. I'm also open to any other suggestions you may have. Best, Mica On 10/19/20 3:44 AM, Jeronimo Pellegrini wrote: Hello, (I sent this from an email address different from the one registered in the mailing list and it didn't seem to be sent, so I'm sendingit again from the correct email. Sorry for any duplicates) I have been working on the pt_BR translation (of both darktable and its manual). I usually translate using po-mode in Emacs, but of course I can adapt to some extent. :) How much of my workflow would change? One thing that would be difficult for me is to translate directly on a web browser. I may be old-fashioned, but really, I never got to do any reasonable work on web interfaces. Will it still be possible to use an editor to do translation work? Also - would the darktable manual translation need to be re-entered or reworked? You mentioned that translated segments would be suggested, so I suppose the whole document would need to be entered again in weblate -- is this correct? Thanks, Jeronimo Mica Semrick writes: Before we open translations on weblate, I will take the current PO files, for both the application strings and the user guide, and make translation memory files out of them. I can then import them into weblate (PO editor also supports TMX files in recent versions), and if possible, translated segments from the old manual will be suggested in the dtdocs translation. I don't have high hopes for a lot of matches, since quite a bit of dtdocs has been rewritten, and translations just don't work like that. The other possibility is that we use machine translation for the first round, then let translators edit that translation. We did machine translation from one of AP's French articles to English, and I was not impressed with the quality of the translation, but hey, we can always give it another shot. On 10/17/20 3:12 PM, jys wrote: On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: Probably a good move and I understand that rewording was needed but that it is tad harsh for translators. I may be optimistic/wrong here, but the situation for translators may not be quite as bad as it sounds. From the parts of the re-worked docs that I looked at, the emphasis has been on making the language resemble compact native English. Assuming that translators tend to do the same when writing their own native language, there may not be much need for changes overall. Translators would need to scan for *semantic* changes, and hopefully most of these would be related to updated information, which they would already need to deal with anyway. That's my main concerns. Having the doc "away" from main repo will not help. I don't know why exactly, but I've seen that on different projects. Maybe because the doc is away it feels less part of the project and there is less incentive to care for it? Again, possibly optimistic, but the new setup has a distinct advantage in that text can now be easily edited even within the github web interface itself, reducing the need for contributors to maintain a local git repository just to "scratch an itch" regarding updates or other improvements. In a sense, some technical burden has been shifted to the maintainers of the repo, who will need to sift through (possibly many) issue reports and accept (or not) PRs, perform any needed copy editing, etc... but they seem willing to do this. :-) ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Introducing dtdocs
Hello, (I sent this from an email address different from the one registered in the mailing list and it didn't seem to be sent, so I'm sendingit again from the correct email. Sorry for any duplicates) I have been working on the pt_BR translation (of both darktable and its manual). I usually translate using po-mode in Emacs, but of course I can adapt to some extent. :) How much of my workflow would change? One thing that would be difficult for me is to translate directly on a web browser. I may be old-fashioned, but really, I never got to do any reasonable work on web interfaces. Will it still be possible to use an editor to do translation work? Also - would the darktable manual translation need to be re-entered or reworked? You mentioned that translated segments would be suggested, so I suppose the whole document would need to be entered again in weblate -- is this correct? Thanks, Jeronimo Mica Semrick writes: > Before we open translations on weblate, I will take the current PO > files, for both the application strings and the user guide, and make > translation memory files out of them. I can then import them into > weblate (PO editor also supports TMX files in recent versions), and if > possible, translated segments from the old manual will be suggested in > the dtdocs translation. I don't have high hopes for a lot of matches, > since quite a bit of dtdocs has been rewritten, and translations just > don't work like that. > > The other possibility is that we use machine translation for the first > round, then let translators edit that translation. We did machine > translation from one of AP's French articles to English, and I was not > impressed with the quality of the translation, but hey, we can always > give it another shot. > > On 10/17/20 3:12 PM, jys wrote: >> On Sat, Oct 17, 2020, at 09:34, Pascal Obry wrote: >>> >>> Probably a good move and I understand that rewording was needed but >>> that it is tad harsh for translators. >> >> I may be optimistic/wrong here, but the situation for translators may not be >> quite as bad as it sounds. From the parts of the re-worked docs that I >> looked at, the emphasis has been on making the language resemble compact >> native English. Assuming that translators tend to do the same when writing >> their own native language, there may not be much need for changes overall. >> Translators would need to scan for *semantic* changes, and hopefully most of >> these would be related to updated information, which they would already need >> to deal with anyway. >> >>> That's my main concerns. Having the doc "away" from main repo will not >>> help. I don't know why exactly, but I've seen that on different >>> projects. Maybe because the doc is away it feels less part of the >>> project and there is less incentive to care for it? >> >> Again, possibly optimistic, but the new setup has a distinct advantage in >> that text can now be easily edited even within the github web interface >> itself, reducing the need for contributors to maintain a local git >> repository just to "scratch an itch" regarding updates or other >> improvements. In a sense, some technical burden has been shifted to the >> maintainers of the repo, who will need to sift through (possibly many) issue >> reports and accept (or not) PRs, perform any needed copy editing, etc... but >> they seem willing to do this. :-) >> > ___ > darktable developer mailing list > to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
Re: [darktable-dev] Re: Introducing dtdocs
This is great. I'm relatively new Darktable but felt the need to refine the copy. Reducing written word down to its core parts does take time. There's a saying, "Sorry I didn't have time to write less." :) About the choice between Hugo or Jekyll, I realize that some may like the speed of Hugo, but Jekyll does have incremental builds (I read that Hugo doesn't have that). In my experience working on sites with thousands of pages, by using the incremental build tag and limiting the number of languages on my local end, I would have a site I can re-test in a second or two. Hugo is written in Go also. That might be obvious from the name, Hu"go", but it probably isn't to most. So I suppose those who might want to do the documentation would need to access whether they want to use a Go binary over Ruby. J On 2020-10-19 02:44 UTC Mica Semrick wrote: > Hey Torsten, > > Minimalism is a basic tenant of technical writing. We should strive to > convey the "thing" in question using the fewest words and image to (1) > reduce the maintenance overhead and (2) more words/images generally do > not make the "thing" clearer, in fact, quite the opposite. It often > muddies the picture. > > The current documentation has a colloquial verbosity to it that (I feel) > doesn't enhance the understanding of the reader. Similarly, there are > images that don't enhance the readers understand either, for instance in > the current documentation there is a image of every since module just > ahead of the textual description of that module. In the new docs, we've > split out module references into their own section and we assume you > have darktable open in front of you (or you know what a module generally > looks like) and thus we omit the image. > > If there are specific instances where you think not enough is written, > you are encouraged to open an issue. > > Hope that makes sense. > Hey Torsten, > > Minimalism is a basic tenant of technical writing. We should strive to > convey the "thing" in question using the fewest words and image to (1) > reduce the maintenance overhead and (2) more words/images generally do > not make the "thing" clearer, in fact, quite the opposite. It often > muddies the picture. > > The current documentation has a colloquial verbosity to it that (I feel) > doesn't enhance the understanding of the reader. Similarly, there are > images that don't enha ___ darktable developer mailing list to unsubscribe send a mail to darktable-dev+unsubscr...@lists.darktable.org
