Sanic Guide Development Proposal

Moving forward
#1

with sanic v21.3 released, the new sanic documentation were also released. And it’s support English and Chinese.
It’s real a exciting news. but there is also still many problems. I also think about these problems:

  1. How to make the style of documents more uniform ?
  2. How to make the work of translators easier ?
  3. How to make it easier to update these documents?

Therefore, we should specify a clear plan for the development of sanic documents in 2021.
The goal is to make document maintenance more convenient, easier and high-efficiency.

And this is our plan:

The theme of sanic-guide program development this year is efficiency.

  • v21.6, customize a perfect writing format,
    and try our best to ask all contributors to Create according to the writing standard:

Although we have many excellent document contributors,
the writing format of documents varies from person to person,
which brings great challenges to document display and translators translation work.
We urgently need a unified writing style to ensure the consistency of document display.

  • v21.9, Customize translation dictionaries for proper nouns:

We also have many contributors to document translation,
but because of the different translation habits,
the same proper noun is likely to be translated into different contents.
Therefore, we also need to customize a proper noun dictionary to help translators unify their translation style.

  • v21.12, Find the most efficient way to organize documents.

Our document now has 7 chapters and more than 50 documents. As time goes by, documents will become more and more.
New content is easily overlooked by translators. We need an effective way to help translators find the changed
content quickly and accurately.

This is only an initial plan. If you have any good suggestions, please say them.

We appreciate your opinions very much.

1 Like
#2

I have drawn up a temporary writing standard and issued an issue Writing Specification.

If you are interested, go and have a look, and then give your opinion

#3

Thanks for kicking off this discussion. We have been lacking in documentation for a long time, and I think that this really needs to have first class attention. We’re headed in that direction, and I appreciate the effort you put in to give us milestones throughout the year.

I have no specific comments about anything you proposed other than to say that I agree.

The only other thing that I am somewhat concerned about is how we can keep the languages in sync. Changes that correct a typo or other mistake are one thing. But, it is not uncommon to have someone submit a PR to clarify a topic. How do we make sure that gets carried through all the languages? Larger changes that are related to new features and releases should be easier, but it carries the same essential problem.

#4

I have been thinking about it too. but I don’t have good ideas.

Although there are some platforms for collaborative translation, the effect and ease of use are not ideal.
I have carefully considered this matter and think that there are two key points that are difficult to achieve：

  1. How to ensure that every revision can be notified to translators in all languages.
  2. How to ensure that every revision is translated in time by translators

  • To solve the first problem, we may be able to create a special channel on discord to ensure that every modification can be pushed in time. This channel should prohibit chatting, and only be used to push change notification, so that translators can correctly locate the position of the last translation.

    Of course, I don’t think this is the optimal solution.

    I have read flask docs, which don‘t support multiple languages. The only Chinese document is a project created by another contributor, and the domain name is inconsistent. I’m not sure if this is officially recognized.

    The django docs have their own repo and they are translate through transfex. but transfex is not free

    I have also found some platforms for collaborative translation, but these platforms are not easy to use and the supported document formats are very limited.

  • On the second question, it is voluntary, and we can’t ensure that translators are always on standby, which is a great challenge to the immediacy of our document translation.

We still have a solution to the first problem. Even if it is not optimal, we can optimize it slowly in the future, but we really can’t solve the second problem :fearful:

#5

Exactly. I think the best we can attempt to do is create some sort of system to track the relative position of various languages. That way, at least if we merge a change in one language, we could have a record of what’s missing.

At rhe very very least, maybe set some standard. Docs change is approved in language X, all contributors have Y days to get it in before merge. If not, then the merge includes a notice at the bottom of the page (we keep a library of canned text in each language) that we can copy and paste that says there are missing updates.

If the change is purely code, then the person making the change is responsible for doing it in each file.

#6

I looked at that website and signed up for a call with them (15 mins demo). Anyone that is available today at 19:30 utc+3, let me know. @misss85246 might be pretty late there.