grpc / grpc.io

Repository for the gRPC website and documentation
https://grpc.io
Other
420 stars 444 forks source link

Migrate documentation from grpc doc folder to the grpc/grpc.io repository #98

Open remyleone opened 4 years ago

remyleone commented 4 years ago

Currently, I see two main sources of documentation for the grpc.io:

I think it would be a good idea to have a centralized place for the documentation so that contributors know where to contribute new content.

I would suggest to migrate it here as it will have a clean URL that will make it easier to find through a web search.

lucperkins commented 4 years ago

From what I can gather, the docs in grpc/grpc are intended for developers of gRPC, whereas the docs here are intended for people writing gRPC-based services. I’m not sure it’s advisable to combine these sources into one. Though I do think that (a) the purpose of each source should be made more clear on both sides and (b) any info that’s in grpc/grpc that may be of use to end users should be added to these docs.

remyleone commented 4 years ago

I think having a single site with clear content architecture (user of gRPC / developer of gRPC itself) could build a large audience. This website could help create bridges between the two communities and improve communication for both.

muxi commented 4 years ago

@srini100 - office hour cc

lucperkins commented 4 years ago

@muxi Could you please explain why you added this comment to 10+ issues today?

srini100 commented 4 years ago

@lucperkins, sorry, that's the process for the grpc team to delegate the issues if no activity is seen for a week. Should we change it to ping you instead?

srini100 commented 4 years ago

@lucperkins, if there is an assignee then we won't triage the issue. Please set the assignee if you can.

lucperkins commented 4 years ago

@srini100 Understood! And good to know for the future. This issue is currently in the discussion phase so no assignee yet.

chalin commented 4 years ago

I've seen a similar setup as a part of other projects where the main project repo docs are considered "engineering notes", best maintained by core project developers.

That being said, I do believe that there is duplication in some of the documentation. For example, the last section of the Java tutorial refers the reader back to the Java examples README. But the README contains instructions that are already found in the Java Quick Start. There might be an opportunity to clean things up a bit here.

dapengzhang0 commented 4 years ago

Office hour ping to participants. This issue is still not assigned to anyone and not active over two weeks.

srini100 commented 4 years ago

Assigning to @chalin, so we can skip this in our triaging effort each week. This doesn't mean this issue is actionable yet.