Re-organize translation docs by Divio's system #141

gonzalo-bulnes · 2021-01-27T13:56:18Z

Status

Ready for review

Description of Changes

This draft PR explores re-organizing the translation docs with the Divio system in mind. The goal wasn't to achieve a production-ready slice of documentation, but to draft enough of it to be able to evaluate if it's a direction worth pursuing. Edit to add: the answer to the first iteration was "worth pursuing", the goal of the second iteration is to start checking how all pieces can fit together. Edit 2: we're now refining the content within the new sections.

Worth looking at

how the sidebar navigation looks (as an overview of the section)

Fixes #134 (maybe!)

Questions / goals:

Would consolidating both the i18n and l10n pages in this way make this content easier to consume for the different people who need it?
Would that also make it is easier to extend and maintain?

Checklist (Optional)

Doc linting (make docs-lint) passed locally
Doc link linting (make docs-linkcheck) passed
You have previewed (make docs) docs at http://localhost:8000
The commits are squashed as intended (no fixup in commit messages)

docs/development/translations.rst

eloquence · 2021-01-29T07:10:20Z

Hi @gonzalo-bulnes, thanks a lot of taking a stab at this. In general I'm a fan of the Divio model for organizing docs, and we've used similar how-to language in recent PRs as you may have noticed.

If we follow this organization, it may be useful to occasionally spread in breadcrumbs from one part of the docs to another, but overall I do think this is a direction worth pursuing. Curious what @rmol thinks, and would also be great to get comments from other translators, e.g. @KwadroNaut @Claudinux @AO-LocLab

gonzalo-bulnes · 2021-01-29T07:38:48Z

Thanks for your comments! I've noticed some how-to language indeed and have been thinking a lot about the Divio model since seeing your reference to it in another issue. I've often found writing documentation quite difficult to be honest and Divio's insights got me thinking about approaching it in a different way. It is a very insightful and useful guideline in my opinion.

I'll follow up on your inline comments. The file is an early draft somewhat intentionally: I didn't want to spend too much more time that the necessary to see if now was a good time to go in that direction.

I can clean things up a little to make a broader review easier to everybody else and make the intention clearer, then iterate from there. Thank you for the guidance! 👍

docs/development/translations.rst

gonzalo-bulnes · 2021-01-30T15:47:56Z

That is somewhat cleaner, and I think the intent should be clearer. @rmol @KwadroNaut @Claudinux @AO-LocLab Now is a better time if you want to chime in 🙂

Two words on scope

I only touched on the l10n section for now and this new page is primarily talking to translators. I think that ultimately the i18n docs would fit well in this page as well, but I believe it would probably make sense to focus on the translators' docs first, then open a second PR to integrate the development aspects.
I was thinking of adding a Get started internationalizing SecureDrop section, right after Get started using Weblate and go from there. Or maybe Get started using gettext, or maybe renaming the existing one to Get started translating SecureDrop... let's see when we get there.
I added a placeholder for a User interface glossary just to check the fit. I am thinking that that section/glossary could be the outcome of Extend the glossary aiming at making the UI more accessible #117 (specifically what I was thinking as User Interface Copy a few days ago). The intention would be to gather terms like Log in, Sign up, Check for replies, etc. with the purpose of making consistency easier and provide some background that could help translations. It could be a point of contact between developers and translators for terms that are neither technical nor specific to SecureDrop but are used intentionally across the user interface.
I also intend to remove that placeholder from this PR eventually, because it can be added as a separate PR, but I think it's useful to see how all reference docs and their different purposes would fit together.

That's what I've in mind right now -thoughts in progress!- please chime in, comments and thoughts welcome!

docs/development/translations.rst

KwadroNaut · 2021-02-01T23:56:01Z

Thanks for inviting for my input, I don't have enough bandwidth right now to dive deep into this, including order, level... In general it looks like you're replacing the l10n page and keeping the i18n seperate, which is alright: one for developers, one for translators. On top of that, the merge isn't too big.

I'm not sure if the whole diwa-concept is a useful thing here. Guiding someone through setting up a weblate account and only telling at the end what SecureDrop is and that it uses Weblate is a bit counterintuitive to me. I would really put that background introductory stuff at the start.

Regarding maintenance and usage: some low level irrelevant pieces should be removed. 'How to register with e-mail in weblate:' it's a bit too much of the level 'take a sharp knife and a cutting board for chopping the cucumber.' When there's a change in colors or the button moves to the left in weblate your documentation needs an update.

What I'm not sure of where to add: the typical introduction questions when one starts: should I use the formal form for my language? For both journalists and sources? Glossaries can help, but I think they often lack the answer to such questions.

gonzalo-bulnes · 2021-02-02T09:42:17Z

Regarding maintenance and usage: some low level irrelevant pieces should be removed. 'How to register with e-mail in weblate:' it's a bit too much of the level 'take a sharp knife and a cutting board for chopping the cucumber.' When there's a change in colors or the button moves to the left in weblate your documentation needs an update.

I don't disagree at all on this. I didn't pretend to make a call on the content in the scope of this PR and so far I only re-organized the content that was already in the l10n page. I am not sure either how useful it is to explain how to register an account or leave a comment, but I also believe those instructions were written for a reason. What do you think we should do @rmol @eloquence? If you have a longer-term vision for the content of these docs I'm happy helping to figure out a way to get there incrementally. (And some of that may inform the structure of the page, indeed?)

gonzalo-bulnes · 2021-02-02T09:53:13Z

What I'm not sure of where to add: the typical introduction questions when one starts: should I use the formal form for my language? For both journalists and sources? Glossaries can help, but I think they often lack the answer to such questions.

💯 I would find this kind of information immediately useful too. It is as much about defining the "voice" in English as it is about providing guidelines for translation (and I've wondered about it myself). @ninavizz Is it safe to assume you're the best person to ask about language guidelines for devs and translators working on the source / journalist / admin interfaces?

gonzalo-bulnes · 2021-02-02T10:32:32Z

I'm not sure if the whole diwa-concept is a useful thing here.

I'm skipping this part because I'm not sure I understand what you meant @KwadroNaut, and looking up "diwa"/"diwa-concept" didn't get me very far. I you could re-phrase, I'm sure I'm missing something 🙂

Guiding someone through setting up a weblate account and only telling at the end what SecureDrop is and that it uses Weblate is a bit counterintuitive to me. I would really put that background introductory stuff at the start.

This is a very good point.

On the first hand, thinking aloud: I think the docs are not necessarily meant to be read linearly, but 1. the fact that you did tells something, and 2. I wondered myself if creating a single file or multiple separate files for the four sections was better. (I finally thought a single file seemed better but that's a somewhat different discussion.)

On the other hand, with the Divio model in mind, I think it makes sense to start by the tutorials (that are meant to show the newcomer they can achieve something meaningful quickly and are the most motivating). We don't have any tutorials at the moment, but I think the Getting started section is the closest to that.

From there --I'm looking at the Divio's model diagram as I write-- I guess the choice of going to the How-to guides (clockwise on the diagram) or Explanation/Background information (counterclockwise) would depend on what the intent is:

Tutorials relate to How-to guides in that they are practical, and that direction would encourage getting started doing.
Tutorials relate to Background information in that they're both most useful for studying, and that other direction would encourage getting a better understanding before getting started doing. Which I think also makes sense, and maybe makes more sense in the case of an high-context activity like translating. (Still thinking aloud.)
Once chosen a direction I would follow the circle and close the loop.

I'd love more thoughts from everyone, but I'm tempted to move towards the sequence: Getting started > Background information > Reference > How-to guides. I believe there are limits to reading the page from top to bottom anyway, but I think there is a very valid point for presenting additional context that will be useful when translating (or writing copy!) immediately after the introduction.

Thank you so much for your input @KwadroNaut!

eloquence · 2021-02-27T01:49:22Z

Thanks again @gonzalo-bulnes for taking a stab at restructuring our docs. I left some more comments inline; let me know if you are interested in working further on this. If so, given the large scope, it may make sense for us to chat synchronously sometime in the coming days :)

gonzalo-bulnes · 2021-02-27T01:54:46Z

Hi @eloquence! Awesome, I'll review your comments later this weekend.

Yes, I am interested in working further on this, I was merely waiting for further comments. It is indeed a large scope, and I think it would be easier to talk through it. (I can post a summary of the conversation afterwards.) I'll reach out to you on Gitter to coordinate. 🙂

eloquence · 2021-03-01T23:49:35Z

docs/index.rst

@@ -115,6 +115,7 @@ anonymous sources.
   development/contributor_guidelines
   development/tips_and_tricks
   development/database_migrations
+   development/translations
   development/i18n
   development/l10n


Just adding a reminder here to remove the old pre-reorg doc :)

I removed development/l10n.rst which is now redundant. (On "translations" vs "localization", I think the document is specifically about translations, but I don't feel strongly about it.)

gonzalo-bulnes · 2021-03-08T11:30:49Z

Note to self: both images and figures can be scaled, and seem compatible with the "click to see image in its original size" feature used in other pages.

eloquence · 2021-03-24T20:45:38Z

@gonzalo-bulnes Just touching base; I know this is a big undertaking - do you still want to proceed as we discussed on this PR in the near future?

gonzalo-bulnes · 2021-03-25T12:48:33Z

Hi @eloquence, short answer: yes.

Longer answer: I was out the past two weekends and weekdays have been somewhat busier than usual, so I've have been picking up some unrelated tasks from my personal backlog that don't require much context.

As far as re-ordering the sections, limiting the number of links (aiming at making the sections more self-contained), consolidating the background information and migrating more content towards the how-to section, I'm fairly confident I can push some changes over next weekend.

The images markup seems straightforward, and opening issues for new content would likely benefit from an overall view of the changes, so I'll likely leave those two aside for now.

gonzalo-bulnes · 2021-03-28T08:53:02Z

[... a reader attempting to locate an answer quickly.] Especially the "Background" and "How-to" sections contain some very similar instructional information, and are both richly populated.

My bias would be to move as much into the "How-to" section as possible (possibly giving "How-to" a bit more hierarchical structure) and to keep "Background" very short. -- thread

I've moved all practical information to the How-to Guides, leaving only the contextual information in Background Information. I think it looks good, and I agree that makes the purpose of each section clearer. Please let me know what you think @eloquence : )

gonzalo-bulnes · 2021-03-28T08:53:15Z

If our main goal with the "Reference" section is to provide a glossary for translators, I would just call it "Glossary" and keep it super-simple: word/definition. Leave everything else for the other sections. Right now it feels a bit unclear in its scope. -- same thread

I've renamed the section to Glossaries, plural, here's why: I don't think the intention is to move the general glossary to the translations page (1), and the translation glossaries in Weblate are different: word/translation instead of word/definition (2). Finally, the EFF Surveillance Self-Defense glossary (3) is mentioned as a fallback for SecureDrop's.

I've also re-ordered the sections from most-used (and probably most expected in the context of translations) to more specific (and probably less necessary for day-to-day translation), and I think that helps making the distinction clearer.

gonzalo-bulnes · 2021-03-28T09:05:24Z

@eloquence My notes from our chat say we talked about ordering the section as: 1) Quick start, 2) How-to ..., 3) Background ..., 4) Glossary.

However, when reviewing previous comments, and looking at the content itself, I think swapping Background and How-tos does make sense and works well, so I did that (last commit just before this comment). Let me know if there was a reason why you had changed your mind when we talked, or if I made a mistake writing down my notes!

Previous comments:

I would put the "Reference" or "Glossary" section at the end. So 1) Quick start, 2) Background, 3) How to ..., 4) Glossary. -- @eloquence same thread again

Guiding someone through setting up a weblate account and only telling at the end what SecureDrop is and that it uses Weblate is a bit counterintuitive to me. I would really put that background introductory stuff at the start. -- @KwadroNaut in earlier thead

eloquence · 2021-04-01T01:25:45Z

@gonzalo-bulnes This is really coming along nicely, thanks for your continued work on it. I think the section ordering is fine as it is now. :)

The only section that still feels a bit confusing to me is the "Glossaries" section -- if you look at it in the outline of headings in the sidebar, you have a heading called "Language glossaries on Weblate" and another one called "Weblate glossary". This to me breaks the principle of obviously disambiguated section titles.

I would suggest consolidating this further -- IMO the three subheadings are an unnecessary level of depth for what is a relatively short, straightforward section mostly linking out to other pages/sections.

docs/development/translations.rst

eloquence · 2021-04-01T23:21:20Z

This is almost ready to merge, I think. The SecureDrop team is off tomorrow, but I'll ask @rmol to take a spin as well next week. Thanks again for all your work on this.

gonzalo-bulnes · 2021-04-01T23:51:32Z

Awesome, thank you for following up so thoroughly @eloquence! I'll have a fresh read through the page myself in the next few days, see if anything stands out.

Note: From the docs, I thought that rebase -S -i HEAD~35 --autosquash would pick up the partial matches on fixup! Spike reorganization, but it doesn't. I'm happy to squash, reword that first commit and update the branch when the time comes, just let me know 🙂

eloquence · 2021-04-01T23:56:02Z

@gonzalo-bulnes I've not used --autosquash before myself - but one way or another, now would be a good time to do a first squash, so we don't accidentally merge (looks up) 35 commits. ;-)

gonzalo-bulnes · 2021-04-02T00:42:16Z

(Rebased.)

- create self-sufficient sections where possible - keep the Background Information concise - move as much content as possible to the How-to Guides - order the sections to allow for sequential reading See https://documentation.divio.com

Using figures instead of images ito enable a full-size link and allow adding captions. Trade-off: unlike the :image: directive, :figure: cannot be used in substituion definitions. Note that setting an explicit width to the image directive is enough to enable to link to the full-size image, but adding a caption makes the feature less likely ot be missed. See https://docutils.sourceforge.io/docs/ref/rst/directives.html#image and https://docutils.sourceforge.io/docs/ref/rst/directives.html#directives-for-substitution-definitions

gonzalo-bulnes · 2021-04-04T21:48:08Z

(Rebased again, to incorporate minor changes after a fresh read-through.)

rmol

This looks good. I find the ordering of the previous version a little more approachable, but the structure of this version will probably make it easier for most people to find what they're after.

I just had a couple of suggestions: keeping the instructions for becoming a reviewer, and moving the "getting help" section to a more global place.

docs/development/translations.rst

Fix name of forum category 'Translations'

gonzalo-bulnes · 2021-04-07T12:41:31Z

Note: I added the two commits independently to make them easier to review, but I can squash them with the first commit of the PR when rebasing the branch.

rmol · 2021-04-07T13:22:03Z

Thanks @gonzalo-bulnes. The time and thought you've put into this is really appreciated. I think we still have a lot to work out, but exploring a logical structure we can adopt has been very useful. The questions that have been raised here (thanks also to @KwadroNaut), like the level of detail and whether we're giving enough guidance for the actual process of translating, can be addressed later. I suspect that even if we reduce some detail that's presented elsewhere, there's enough information we should add that we'll eventually need separate documents. They would support progressive disclosure, so would work for both linear readers and searchers, and could contain all the content we need without being overwhelming.

Thinking about standard organization and structural consistency will also be even more important as we start to translate this documentation, which I'm hoping will happen later this year.

gonzalo-bulnes · 2021-04-07T20:45:05Z

Thanks everyone really! I'm very glad this was useful. I found it super interesting to explore how different docs structures shape the experience for different people and look forward to helping where I can for the next steps 🙂

gonzalo-bulnes force-pushed the reorganize-translation-docs branch from 0203103 to dc38d7c Compare January 27, 2021 14:00

gonzalo-bulnes mentioned this pull request Jan 27, 2021

Extend the glossary aiming at making the UI more accessible #117

Closed

eloquence changed the title ~~Spike reorganization of docs by Divio's system~~ Spike reorganization of translation docs by Divio's system Jan 29, 2021

eloquence reviewed Jan 29, 2021

View reviewed changes