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

Tags: #<Tag:0x00007f7a03dc3d20>

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

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?

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.

@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.

@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.

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 !

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

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.

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?

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. ???

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

@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

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.

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.

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:

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).

sounds good. I’ll put airtable on my list of ‘to learn’ :slight_smile:

I like your approach, @MyriamBoure. I was just wondering about keeping things as draft. I think once the English version is accepted, it doesn’t need to stay in draft mode. We have the whole history in Github: https://github.com/OFNUserGuide/OFN-User-Guide---Master/commits/master

This also enables the managers of a specific language guide to go through all changes once a week or once a month instead of responding to pings and trying to be quick because we want the English version updated as quickly as possible.

Is that history view good enough? Is there a similar view within Gitbook?

Hoooo ! You are a genius @maikel :slight_smile: I went to Gitbook and there is actually a very easy way to see the previous drafts merged !!!
On the left column on “activity” you can see all the latest changes. Within this view you can click on any “draft” merged and if you click on “view changes” you will see in good UX (better than Github) all the changes made so as a non-English user guide curator, you can apply those changes to your language guide (or discuss them if you are not happy with them).


I’ll sum up a proposal later today in a google doc then so we can agree of the “current” agreed upon process and put it in the OFN handbook as the current single point of truth. Hopefully we’ll have time to discuss and agree today in the user-guide meeting !

Ok ! So I prepared a first draft of the new documentation of how to setup and update a local version of the OFN user guide. Here is the proposal : https://docs.google.com/document/d/16DvkxVOI6kjqs7szuAl4UMsEEnBEbtVBAq-a4AgSDvk/edit?usp=sharing

@Rachel I’m not 100% sure for the first steps if this is how we are supposed to proceed to create the new space for the new language, please check and suggest modifications if I’m wrong, directly in the document please :slight_smile:
@lauriewayne1 @lbwright22 @nick @EmilyRogers @tschumilas @maikel @Anna @lin_d_hop (who did comment above) please check if it is all good for you. We might want to discuss a bit more precisely the process of the translation at release time… I made a proposal in the document based on my proposal in the thread, might worth some process check at next global hangout…

Looking forward to reading you ! We have a next call on the 9th october with the “project team” so great if people can give feedback for that date :slight_smile: