A "project" at Hyperledger is a collection of specific maintainers, users, and other developers, code, releases, issues, and other activity oriented around a common software-implemented mission.

This project proposal template ushers originators, designers, implementers, testers of a project through community and TSC approval. The proposal should evolve organically as the proposal moves through the stages of conception, design, approval, implementation, and deployment. The project and hence the proposal may also need several iterations. In its terminal forms, it can also serve as a short manual to the features of the project for users.

This proposal template is descriptive and not normative, a guide rather than the law. Prior templates, like the internet RFC process, Bitcoin Improvement Proposal, Python Improvement Proposal, etc., were used as guidelines to develop this template.

The seed of a new project has to be vetted in a public forum before creating a project proposal. It is best if the project has technical champions who believe in the project and are the maintainers of the project. The technical champions can change in the middle of the project.

Please note that readability is very important. The language of the proposal should be English, if possible, as that is the lingua franca of the community. The Chicago Manual of Style should be followed for an explanation of abbreviations, references, etc. This is extremely important as a clear statement of the problem and its technical details are helpful to coalesce the community around a solution and prompt volunteers. The outline of a project proposal is given below with comments on the sections.

Project Identifier

Support multi-language to help different language speakers learn and use hyperledger fabric at the same documentation website.

Sponsor(s)

Rich Zhao, zhao.zhenhua@gmail.com

Technical Working Group China(TWGC) has been working for a long time to translate fabric documentation, so far we found it is the best way to maintain documentation.

Abstract

Help different language speakers learn fabric in their own language. 

Context

If any, what is this project derived from? What if any is it related to?

Dependent Projects

If any, must be listed, and each dependent project's maintainers must sign off on the proposal before it is considered by the TSC.

Motivation

Hyperledger Fabric documentation is written in English.  For those contributors whose native language is not English, they have difficulty contributing to or using hyperledger projects. If the documentation and log messages in software code can be translated into their own native language, it will help build a larger community of contributors and users. 

Technical Working Group China has been working for a long time to translate fabric documentation, we use a separate repo to host the documentation but if we can use the same website as the English documentation, it would be more official and convenient for users to use. 

Besides, Chinese, we do see other languages are required too.  

Status

TWGC has translated about half of fabric v2 documentation with the current solution, it is available at https://fabric-documentations.readthedocs.io/en/latest/

Solution


The solution needs:


  1. documentation manage framework, sphinx which Fabric is using. Fabric English documentation uses Sphinx v1.7 to manage documentation materials, like .rst, .md files, and the structure layout and build to final output format HTML, pdf, ePUB, etc. Sphinx is a documentation framework based on python, we need to upgrade sphinx to version 2 for more compatible. It has been done through https://gerrit.hyperledger.org/r/c/fabric/+/31667
  2. A repo to store documentation material and collaborate among contributors. Fabric English documentation uses the same repo as fabric code, it is okay for other languages to use the same existing repo, but as the documentation doesn't share the update release pace as code, it is better to use a separate repo to host ALL documentation materials.  All means do NOT separate other language documentation from English documentation, as others are translated from English. Translators/contributors need to monitor English status. 
  3. A translation tool. We prefer transfex.com. Because,
    1. it is free for open source projects. The paid account has a statistics report,  but it is fine without reports.
    2. More importantly,  it is very collaborative,  translators can working simultaneously, translating, reviewing, etc. 
    3. It provides a CLI tx, like git, contributors can use tx to pull from/push to transfex
  4. readthedocs account to host the documentation. Fabris is using it, just need to merge other languages into it.


Efforts and Resources

Suggest using a separate repo to host all documentation material. 

How To

How to host and test the project. How to deploy and use. How does one know that it works?

References

Closure

How do we know that the project succeeded? This has to be measurable if possible. Make references to successor projects if any.

Reviewed By