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