User Guide as a Living Document - how to keep it current/rich/relevant?

Support
1

This topic was born on Slack and seems to have outgrown it. We’re talking about the process for editing the user guide and making sure that user guide editors in all languages can benefit from each others work. Copied here are the slack posts that got things going, starting with a thread from Emily Rogers:

Here’s a suggestion for how we update the User Guide as a group. This is an interim measure until we can get multiple user accounts for Gitbooks, as we currently have to share editing under a single login.
(See here for background, including a video on how to update the guide https://openfoodnetwork.slack.com/archives/C0YJZHLLQ/p1553712446025700.)
I would also suggest the process below is not necessary for fixing small typos, grammatical errors and simple clarification of text.

Recommended Process for bigger changes:

  1. I see a change that needs to be made to the User Guide
  2. I log in to Gitbooks and make the change, naming the draft logically
  3. I share the draft here with a simple naming convention
  4. Comments and discussion take place in a thread, if necessary
  5. At least three of us review the change in Gitbooks and come back here to give it a ‘thumbs up’
  6. Once we have three (?) thumbs up, the change is merged (made live)

I’ve made a sample change and will post an example below for us to practice on! (edited)

Emily Rogers [11:53 PM]
REVIEW EDIT: Edited Value description in Product section
I’ve made a small change to clarify the way we describe Value in the Product section of the User guide. Everyone OK with this?
Discussion in Thread.
Thumbs up to agree.

myriam [12:19 AM]
That sounds great @Emily Rogers! In Gitbooks I’m driven to the main page but if I activate “view changes” then I see in orange the menus that I need to go to to see the changes, it looks pretty straightforward :slightly_smiling_face:

LaurieWayne [4:55 AM]
I woke up thinking about the user guide too today and how information seems to be flowing (or could flow) from Slack to the guide. What if we treated updates to the guide kind of like we treat updates to our code, but instead of bugs we have updates, and the work of updating is documented, shared, trackable, and prioritized? I think it deserves the same attention and disciplines as the code base. An example of how this could work using the tools and processes already in place (as I understand them):

  1. Customer Support person has a question or scenario that they don’t see handled in the user guide, so they post their question in #customer-service. This happens now.
  2. Lots of people respond with different options. Knowledge is captured! Ha! Gotcha!
  3. When best answer is determined now, it just gets lost on Slack, but we can bring it into the light of day: a guide update request is issued in Github (this looks basically like a bug report or pull request – but the knowledge that was captured in all those slack threads goes into the update request.
  4. As happens now with pull requests, the update request is labeled (with things like “good first update”, the user guide section it goes in, and possibly how likely it is that a user will need this information) and given a severity (priority)
  5. You want to update the user guide? GREAT! You claim an update request, make the changes based on the captured information, and flag the update request for review.
  6. Your update is reviewed, merges your update, and the request is closed in Github.

Three things I don’t understand about the code update process (which I am proposing is paralleled by the guide update process): who does the reviewing of a code/guide change, who does the actual merging into the code/guide, and what is the role of the train driver in the process? (edited)

rachel [5:26 AM]
I would suggest you a workflow for new features being added to the guide and another one for updates (but maybe this is what Emily was thinking with “small changes”).
While new addition can be reviewed before merging, I would allow updates to be merged directly. Updates needs to happen regularly and must be done by the support team who needs it. When you answer a user you cannot wait for your submission to be reviewed (no matter the size). So what will happen in the long term (and I’ve seen this in other projects) is that the support team will answer directly in the email to the user and will save the user guide updates for “later”. Later which in most cases turns into never because documentation is not fun and nobody wants to do it especially if there is a lot to catch up. I strongly believe that any support team should always answer with the user guide if the answer needs an explanation (and do updates if there are things missing).

For new features, this is quite different because you will need the product owner to warn you a new feature will be released and you will need input from the product owner on how it works. It is then a longer time frame that can benefit from a more detailed review.

That does not mean you shouldn’t review what was added in updates. But I think this can be done by a simple notification here on slack.

This is quite different from the process we use to improve our code. I will answer in a thread about how things work currently.

LaurieWayne [5:39 AM]
So @rachel can you define what would be an update as opposed to a new addition? I think for updates (small changes) you are suggesting that the process is:

  1. Thing is not in user guide, gets asked and explained in Slack (#customer-service?) or customer supporter already knows answer/notices it is not in guide and needs to be
  2. Customer supporter updates user guide with this new information
  3. Customer supporter answers user question (if there was one) by pointing to the user guide update that they just did
  4. Customer supporter notes the update in the #user-guide channel
    ? (edited)

tschumilas [1:47 PM]
I agree with Rachel that the best time to make additions/changes, elaborations to the user guide, is when a user has requested help with something. The person giving support checks what the user guide says (at least I always do) and then elaborates to the user, OR corrects the guide, OR makes it more clear… So at that moment, the issue is clear in the mind of the support person, and this is the perfect time to suggest a change to the guide. I think the question is - do other people need to review the change and how can that work in a timely fashion. Maybe it depends on the scope of the change?

Emily Rogers [4:36 PM]
OK, so I’m getting the sense that there are a few different types of User Guide Update, and that they each need a different approach. Would it be something like this?

  1. You find a small typo, spelling or grammatical error, wrong word, poorly written sentence or simple problem that needs a tidy up = JUST MERGE IT!
  2. A support issue triggers the need for an edit that clarifies the user experience, or explains something that is not currently well covered in the UG = Make Change, Review/discuss/get agreement in Slack… then MERGE IT!
  3. A new feature is introduced to OFN and needs a relevant section created in the UG = Incorporate new UG content into the code release process, with full documentation of edits and review etc… then MERGE IT!

The process I suggested above would be appropriate in Scenario 2. What @LaurieWayne has described would be Scenario 3. Thoughts?

LaurieWayne [5:14 PM]
replied to a thread:

Nice @Emily Rogers - thank you! I am working on a flowchart for decision making about when to MERGE IT! - I would say I am actually more looking at Scenario 2, which is when something is not well covered, which can manifest as a question in #customer-service - I am hoping to come up with a process for capturing those conversations and making sure we are getting that information in the user guide, or in a wiki or somewhere beyond Slack, which is great for conversations but is not a great repository.

I am considering the possibility that the people coming up with and solving the problems in customer-service are realistically not going to be instantly editing the user guide (and they may not be the right people to be doing it from either a skill, time, or motivation perspective). So if my favorite thing to do is update the user guide, or I just want to make sure a conversation/solution is captured because it should be in the user guide, how do I proceed? If my favorite thing is to do tech support and I am maxxed out on helping users do the things they need to do (while simultaneously learning OFN from more experienced colleagues in #customer-service) how do I proceed and make sure the very valuable conversations and examples make their way to the user guide if I am not able to do it?

If my instance tracks problems and solutions in Trello or Zendesk or elsewhere, how do we capture that information and make sure it finds its way into the user guide?

Scenario 3 seems way more sequential and under control than some of the stuff that’s happening in #customer-service, which is directly driven by users having a problem that impacts their ability to do business or their comfort/confidence with OFN.

I also don’t at all know where to go with it, but how do we keep the English user guide synchronized or at least keep important information, video demos, and such included in non-English versions of the user guide? (and how do we make sure the amazing stuff that non-English user guide writers come up with makes its way to the English one?)

Emily Rogers [9:12 PM]
@LaurieWayne yeh these are good points. I had been coming at Scenario 2 from my own perspective as a ‘contenty’ person who would love to get stuck into the User Guide as soon as a problem is identified! Is it viable to have a global User Guide editor to coordinate everyone’s changes? That way anyone who is inclined to make an edit can go ahead and make it and request the the UG editor to perform the final MERGE. Also, could it be a simple use of tags whereby anything that warrants a UG update is tagged in the relevant Slack conversation #UGedit and the editor can then periodically pick these up and implement.

As for the non-English versions - yes ouch - that’s a big question and I’m not fully across how they are maintained and created now. Though Gitbooks does let you review all changes, so the ‘other language’ UG owners might just need to do a periodic review and update.

2

Thanks for bringing us in here @lauriewayne1!

To move forward, it looks like we have three main tasks:

1. User Guide Update Flowchart
Create and agree on a flow chart for decision making and sign off of edits to the User Guide under two different scenarios:
a) A new feature has been created on OFN and needs to be reflected in the UG
b) The UG is not clear/correct and needs to be changed or improved

2. Feed User Guide Changes from Customer Support
Figure out how to identify & capture changes that should be made to the UG that manifest via Customer Support and through conversations in the Slack #customer-service channel, email, Trello, Zendesk etc - and feed these into the UG update process.

3. Manage Multiple Language Versions
Figure out how to manage UG edits so that they flow through to other language guides if necessary.

I would also like to add a 4th task, which is to agree on an interim updating process while the above tasks are being worked through. If we are aware of changes that need to be made, and resources are available to make them, we shouldn’t hold things up on the way to designing the ‘ideal’ solution. So…

4. Quickly Agree on an Interim Update Process
Prioritise agreement on who can make, review and merge necessary changes right now.

Shall we address these 4 issues separately so as to stay focussed?

3

Yes that is bang-on, @EmilyRogers! I am (supposedly) working on #1 and could I ask that we expand #2 to include other places that changes could come from (for example customer support mechanisms like email, Trello, and Zendesk as well as Slack?

4

Good call, I’ll update point 2 above.

5

Hi all ! Reopening that conversation as there were pretty old drafts not merged in user guide, and seems we need to simplify somehow the process to make it more agile / lean.

Language / instance versions

There are various versions of the user guide. Also some versions diverge pretty much on the way the user guide has been written, like the French user guide is not organized the same way as the English one.
With our move toward “language based user guides” rather than “instance based user guide”, we will need to handle a proper conversation to “harmonize” the skeleton of our user guide, basically have only one version that we translate. Else, in Canada French speaking users might have a version, and English speaking user another one, of the user guide.
I suggest we open a dedicated thread and France can explain why we choose another skeleton. We can see as well with Catalunya and Belgium/German languages if they did evolve the skeleton from the English user guide.

Also a good point would be that we have only one global international user guide to avoid having multiple versions, and use IA to translate from one language to the other. That was suggest by Lionel Lourdin with whom we are at the moment in Switzerland. We can have one English international document, when specificities on some pages like payment methods we can have in this page a section per country for instance, so we only have one version including some country specific stuff. We can use the DeepL.com for instance that would automatically translate in any language that document.
[Btw, we could do that as well for the OFN handbook, super-admin handbooks, etc. It would increase tremendously the accessibility of what we are doing to everyone worldwide !!!]
It’s not yet open source but there are some initiatives working on it, for later :slight_smile:

I added a task in the all-the-things pipe

Keeping track of modifications : post modification moderation and changlog so changes can be applied in all UG versions

Then, if a modification is made on a version, we need to let know other user guide curators so they can apply changes in their local user guides. I like the “changelog” idea. Instead of having moderation prior to release of a new version, I think we could have a “post release” moderation in the case of user guides.
If a user guide moderator change something in a local version of the user guide, we could just have a #UG-changelog channel in Slack for instance, so I can tell “Hey folks, I changed on page XXX of English user guide, switched shipping-method in table from N to Y and changed text to : “xxx”. I think it’s relevant for all language user guide so please update this on your local user guides !”.
For some other changes it will be more linked to customer service : “hey I had a question from a user on xxx and realized the guide was unclear. I reworked on the wording of this paragrapher in the English user guide, might be worth for you to check it in your own local user guides”, etc.

So if a UG creator works on it like once a week, she can go through the last messages on the channel and review the things.

Why not using the same process as in Github when we change the tech documentation ?

For customer support as much as possible we will update FIRST the user guide if there is a question and then send the link to the user asking if all clear or not. I think we need to fix that as a rule for ourselves, so it really forces us to all the time improve the quality of our user guide. So we need really quick reactivity as we want to answer the user in the day, or even better in the hour.

So I don’t think that review process will work, we want to be able to first do the change, then if people disagree we can adjust and iterate.

What about new features ?

For new features I think we should just keep the same process, in the changelog “Hey folks I added a page for the enterprise fee summary report in the English user guide. Please check and if you see anything you don’t understand, comment on this thread. It’s published already but we didn’t communicate about it yet. Let’s first agree on the English version and then all other UG curators can translate in local languages. Thanks for your feedbacks!”
So that way, even if no answer, there is already something we can start with, it’s not blocking the release, etc.

What do you think ? Of course, every language UG curator need to be quite “following” what’s happening, that will be our main challenge I think… but I would say that’s the responsability of instances who use that language to make sure there is a curator who regularly dedicate some time updating the UG…

Any feedback welcome !

@Rachel @lauriewayne1 @EmilyRogers @Kirsten @danielle

6

I agree with everything you suggest @MyriamBoure. 2 additional thoughts: 1. we need a process for documenting any changes - even if they are small - in the user guide everytime we do a new release. and 2. sometimes a change to the user guide isn’t coming out of a customer support situation. Sometimes, its just someone’s suggestion. Like I"m trying to do an ‘editing orders’ guide section now. It is ideal if such sections have other input before we finalize in the guide. Am I missing it- or didn’t we have a process for that - like posting on slack and getting 2 other thumbs up, or something like that?

7

Yes we had a process but it was not working, things were remaining in “draft”, not merged and were getting old… and new drafts were made, and it started to be a mess. What you say is what I suggest about adding a new feature (new page on existing feature, etc.), or we could keep that two thumbs up thing but then we need the draft owner to really make sure it is done till merge quickly… we don’t have a “zenboard” to follow that properly in Slack…
My suggestion is before we move forward I would like to know if the automatic translation can work, @Rachel is going to test if DeepL can answer our need. if it does it means we would have only one document to update so that will impact our process (especially, don’t need to work on a common skeleton for all languages in that case ;-)) Then we can take it from there, clearly document the proposed process, and organize a session maybe to discuss all suggestions, tensions, etc so we agree to “lock” a version of the process and test it, with some meeting further in time to review and see if we need to iterate again. So step 1 = DeeL / automated translation.

8

@MyriamBoure I think that this thread was around the English version of the user guide and how to maintain it. I would remove the translation automation from this discussion, and create a different topic on it.

I don’t see how automation in translation will impact the process of updating the English user guide. Most people who worked on a local version of the guide (Guida, Anna, me, Oxfam’s team) are not maintaining/editing the English guide.

9

@Rachel it has an impact on the thing I proposed for instance having a thread to share any change made on a language version so that others can know and see if they want to apply on local version. We can open another thread to investigate and discuss that auto translation point of course, it does make sense, but for me they are connected.

10

Ok, so given the tests @Rachel did with automatic translation of the user guide (see here) it seems we are heading toward a consensus that we won’t have just one version we maintain and delegate all the other language version to some automatic translator tool…

BUT nevertheless, I think we can still propose to maintain and update only one version of the user guide, and only manage pure translation of that guide in language specific user guides (that will require though that all French transifex translation are quite harmonized I guess, like @Rachel if we translation order cycle “cycle de vente” in Offrance and “cycle de commande” on the French-Can translation, we will have the same issue that you mentionned with DeepL…)

To take back here some proposals made by @lin_d_hop here let’s see how we can go with that proposal:

1- Unify the user guide. For me it means we gonna have only one version of the user guide, but then translated in various languages. If a local curator want to modify the content beyond pure translation, modifications need to happen first in the master version and then translation should be done.
Even if we did some work on during the last weeks in the French version, I still think only the English version can be the master one, and we could reverse translate the French version, and rethink some bits where it needs to be “internationalized” like the payment method descriptions, maybe review the page to specify in which country which payment gateway is available, etc.
If we all agree on that let’s keep this specific conversation here : User guide harmonizations : what could be our new common skeleton?

2- Organize some form of notification system whenever a change happens in the master English guide (which in our process will be the single point of truth, so any change should be made first in the English user guide) so that all language version curator of the user guide can be notified and translate the content (just as we do with Transifex today somehow…). There is no Gitbook / Slack integration to do that, I don’t know if there is an easy tech way to send a notification to a slack channel for instance whenever a new draft is merged with a list of all modifications… maybe through github as there are synchronizations between Gitbook and Github and there is an integration I think between Slack and Github to get notification if a new PR is merged for instance, to see the content of that PR.
The first step I was suggestion was to have a dedicated Slack channel channel where we share anytime we do any modification to English user guide so translators can regularly take the history of notifications to translate modifications.

Btw this is valid both for updating existing content and adding new ones. This might trigger some conversation like when I translate a new page someone wrote in the English guide, I might find unclear the way it is explain, so might suggest an improvement in English version instead of just adapting the content in the French version, which is what we have done until now…

3- This setup will allow also to easily organize some automatic translation, or delegate that tasks to some local freelance contractors potentially, or anything else interesting in the future…

@lin_d_hop @Rachel is it aligned with your visions and proposals ? @lauriewayne1 @tschumilas @EmilyRogers @Kirsten @Theodore @luisramos0 does this make sense as well ? I’m happy to move forward the conversation in the other discourse thread on content harmonization, aligned with point 1 mentioned here if everyone agrees. For point 2, two options : start with specific Slack channel and manual notification, or integrate, but I’ll need someone more techy to investigate auto-notification (@lin_d_hop?).

Thanks for your feedbacks !

11

So for clarity:

We need @Anna @Theodore @lbwright22 @tschumilas @EmilyRogers @Rachel (and others that I have missed) to agree that:

  1. We have a single user guide as the primary user guide. The proposal would be the English guide.

  2. All updates are made to the English guide. Then other languages are translated from the English guide

Once we agree this we can move forward on creating collaboratively the proposal for the skeleton structure of the user guide.

1 Like
12

As I have previously said I am not confident to update the English guide in English.

If I understand the proposal correctly, as a support person, when a user ask me something I would need to first write the user guide in English, post it to notify for review, then translate it in French and then send it to the user. :exploding_head:

That seems a lot for a single person to do. I’m afraid that this would lead to people doing support directly sending the content per email and not updating the guide.

Also for it to work it would mean that non English instance would need people speaking English for their local support. This does not make sense to me.

I would prefer keeping adding French content in French, but improving our notification system for other user guide updaters.

So in a nutshell: I don’t understand why English should be the source… if we have people that can dedicate time to the user guide in other language, I don’t see why the English guide cannot be a translated guide as well. So we just need to be better at following the updates, just whatever the language.

DeepL translate from English to other languages, but reverse is also true.

13

Hi all
As someone who only speaks one language I can see the problems with asking everyone to contribute in English if it is not their mother tongue (I wouldn’t be able to contribute in French, German or … if that was the master language).
Would it be an idea to have a Trello board with changes made? Apart from when new features are added to OFN are there many changes made to the user guide each month? How much of a hassle would it be for person in country A who changes the guide in their language just to notify everyone of what they have done and for us to rephrase the content into our language so it reads smoothy for the native speaker?

14

I understand @Rachel’s point. FIrst priority has to be to get the user their help - in their language. Second step is to update the guide in that same language - whatever it is. Then - we need to find a way to get it into English, Spanish,… I have some experience in another global project that always required translation - and the wording was VERY particular - just like in OFN. You always translate into your native tongue - because that is where the finesse of language matters. I’d be happy to take draft English translations if we had them, and then review and finalize them - if that is helpful @Rachel . And - re: French-Canadian vs French in France - at one point one of our francophone volunteers here thought there were lots of differences. That volunteer is not with us anymore and I don’t have a francophone speaker/user to help me. So - I’m thinking that at least for now - we would just default to a single french – and I’m wondering if maybe we should do that in transifex anyway. Because right now, I"m just taking the french translation you do @MyriamBoure and cut and pasting it into the French-Canadian file anyway. (Since I don’t have anyone else here to do it). We can always revisit this if we get more francophone users of OFN here. ???

15

Hi, and sorry for delay! I think it’s a good idea to have this English Guide as the primary one, also, as rachel i don’t feel confident to update it in english, in catalan we just have translated english UG. Having a space to update UG is a great idea, and I think that having a board on trello about it could make things easier, ordered and where we can also see the needs of users that are not reflected in the UG. I would also like to see how you are adding content in France and in other instances. But I do believe that having a reference UG (of course with territorial differences regarding price, for example) is a good initiative! (As far as translations are concerned, I just started to deal with transifex, DeeL looks good too and at the moment I don’t have an opinion about it). So, answering to @lin_d_hop I Agree with both points

1 Like
16

@Rachel @Anna
What if we said every write in your own language, but there is a requirement to make sure one version is always kept as the single-point-of-truth user guide.

Proposal:
People write userguide additions/updates in their chosen language and then they use a web-tranlsate tool to create the English. They then ask in the #user-guide Slack channel for someone to check and merge the English.

The advantage of having English as the base guide - the single point of truth - is that web translators work best with English and more people speak it. But I agree that it will be limiting if all updates are only done in English.

1 Like
17

I like the idea of a single point of truth. I also understand that it’s too hard to update another language before updating the local language. @lin_d_hop’s idea is a great alternative. Additionally, when the English guide is changed, we still need to update all other languages. I’m dreaming of a bot which opens pull requests for all other languages. But for now, the same Slack message about reviewing the English guide could serve as trigger for other instances to update their user guide as well.

18

Updating the English user guide only (this is the only one I feel confident in), which I think means viewing it as the “default” guide/language, may deprive us of a lot of the contribution of exclusive writers in other languages, many of whom may be energetic and dedicated in producing the detailed, accurate content that is so important to the experience of the users. For instance, @Rachel is most comfortable in French, and in fact has said she is not comfortable updating the English guide, at least in its final version.

I think the main thing that’s keeping writers in all languages from contributing equally is the right process for synchronization - if @Rachel (for instance, merci Rachel for letting me use you as an example) comes up with a brilliant explanation in the French user guide, the existence of that content should be known and available for integration to all other guides right away, and it should be easy to tell when things aren’t synchronized between and among any (n) languages. I guess Gitbook doesn’t do this.

The problem with using Trello and Slack for tracking is that they are busy, noisy environments (that can, however, have notification built in, which could add to more noise or be useful). What if we set up a simple excel-like Airtable to note changes to sections (rows) across languages (columns)? Easy to see (like in Transifex) when there is an untranslated section in a given language, and easy to compare (for polyglots and for the purposes of initial machine translation) to see how different instances interpret the explanation for a section. Airtable would also allow for easy storage and tracking of assets like screenshots which can be a pain to recreate.

Here’s a scenario: Rachel makes a change or addition to the French guide, noting the section, function, and a link to the improvement in the table. I go in with the aim of making my own update, and a quick glance shows that there is something new about a feature or function, and Rachel has made a change I need to look at and integrate. Even though my French is comme de la merde, I can go to the French guide section she links to, do at least a quick Google Translate, use my native English speaker skills to smooth it out a bit, ask Rachel or anyone else who has facility in both languages and OFN for a sanity check, and publish. @Anna can do the same thing, and if I don’t get around to updating the English guide before she has time, she is still able to work on having the most current possible guide in Catalan.

As I see/experience it, the main drivers for user guide updates are (1) code/UX changes and (2) questions from users. In the first case, it seems straightforward enough to integrate the update (or answer the question “if a user/admin guide update is required as a result of this change, has it been completed?” in the affirmative in order for a feature or fix to go live). The one where we are responding to a user question is harder, since (I am thinking especially of you @tschumilas) the user support/response job is a related, but very different task from updating documentation - one usually has to be done more urgently and is narrow in scope as a specific question is answered, and the other requires more careful, comprehensive explanation that may involve multiple cases or applications. I don’t think it’s realistic to expect that someone in support/training/explanation mode will naturally switch gears into documentation mode and update the guide in their language(s) on any consistent basis. So what if @tschumilas could take a minute to note in the Airtable a feature, function, or explanation that needed to be updated, and she or someone else could pick that up and add it to the guide in their own most comfortable language, thus moving the process ahead as described above?

All this is to say: I think that for a while at least, it would be helpful to have a guide team with representatives from every language, who tunes and maintains an agreed-on process, and meets on some regular basis to talk through issues, get assistance, and offer appreciation and gratitude to skilled/prolific guide updaters.

19

Wahou, lot’s of ideas :slight_smile:

@lauriewayne1 I get your point and proposal on Airtable, and @Rachel I also agree with your comment, and I see also that it give twice more job to non English speakers when doing UG update, and can be difficult for people who don’t feel confident in English.

But I still think there are more advantages in having a single trustful version of the UG, and this one being EN, for the following arguments:

  • when I’m updating French UG, either because code change, release with new things in it, etc, I’ll usually update various pages at the same time. As one change can affect multiple pages, etc. When I do that, I find it more complicated to have Airtable open and list one by one every paragrapher à I change, sometimes maybe only few words here, few words, there, etc. Than opening a second browser with English version and doing it in both at the same time.
  • about the screenshots, they also need to be “translated” (taken in the language version)
  • having an international shared common version will force us to phrase and think the way we document in this international perspective, which seems necessary if we have language UG (and not country ones). For instance, if we add a new payment method, in a global thinking of it we would have in this master version a table with the various payment methods available and which one can be used in which country where the OFN is deployed. Whereas we might not “think” that way if we just update in our own version, it’s just so easy to forget that the French guide is used in Canada, Belgium, and who knows, maybe some French expat in Australia…
  • when a news instance join, they want to create a user guide from an existing one. It’s probably easier, until Esperanto becomes used, to consider English as the pragmatic pivot language and we want them to have access to the trustful and up-to-date version they can then translate in their new language
  • especially, for small corrections it is more painful to document in airtable than just do the change …
  • if I translate in french and then when you do in English you ask a sanity check (which I understand) it also take me complementary time on it anyway, and when I have my head in it when I’m in the translation, it probably doesn’t take me so much more time
  • Having many notifications in many directions will make changes hard to follow

This being said, I like your idea though of having, maybe in the current Airtable in a UG dedicated section, a sandbox of “improvement suggestions” where we can from the interactions we have with user, if no time to update the UG, record that we think we should add something on that, that anyone could take and do.

So my proposal would be a bit in the direction of @lin_d_hop and @maikel with some bits of what you propose @lauriewayne1 and some notification aspect mentioned by various people:

  • People write userguide additions/updates in their chosen language and then they use a web-tranlsate tool to create the English and leave it in draft mode. They then ask in the #user-guide Slack channel for some native English person to check and merge the English.
  • If the update is done by en EN folk in the English master version, they leave it in draft for a short period and notify in #user-guide Slack channel @channel so every translator knows they have to translate in their own language. leave as draft enable to see all the changes… if has merged, changes in English won’t be tracked and will be impossible to update the other versions
    [those two points work for small updates with new releases, customer support, etc. but also for new features]
  • if when we do customer support we realize something is missing in UG, we open a task in Airtable for someone to pickup later (sandbox user guide)
  • Our release process should include making the relevant updates in user guides (new feature, or change that affects user guide). IMO they should be done before we release so we can link UG so users can see how new features work, etc. In that case if done first in En, we should have some “release draft” that are left 1-2 days in draft so other language translators can see the changes in English version.

That still feels a bit complex, but it doesn’t seem there is a simple process possible here…

I don’t think Trello is adapted, as how would we move the cards, for instance “I changed that sentence in my UG”… who moves it ? when everyone has checked they did change ? …

I wouldn’t object if other think we want to try first the Airtable tracking you suggest @lauriewayne1 and if people want to try this solution first.

Side thought : I think that if we don’t manage to implement an efficient process on having a single common UG, it questions for me the fact of having language UG instead of instance UG… as I see the mess it will be for support person in an instance if they have to deal with different support documentation depending on who contact them locally and which language they speak. We are in the middle of this “find the balance between efficiency through mutualization / cooperation, and resilience through decentralization and local action”… interesting process, I guess we’ll learn a lot and we could write an article to share our experience with other community at the end of the process :wink:

20

Thank you @MyriamBoure I love it and totally agree that simple is more likely to be successful.

I am very happy to proof/edit any additions from anyone who would find that helpful (native speaker or not).