You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@servicecomb.apache.org by JICHUN LIU <jl...@hotmail.com> on 2018/05/13 02:17:20 UTC
答复: [Discussion] Improve documents of serviceComb
Maybe we can learn sth. from the document of Spring Cloud and Vue. Both have a lot of experience on document, usage guide and demos.
-----邮件原件-----
发件人: Bin Ma <ma...@gmail.com>
发送时间: 2018年5月12日 23:36
收件人: dev@servicecomb.apache.org
主题: Re: [Discussion] Improve documents of serviceComb
Personally, if I was a user of the first contact with ServiceComb, I would like to get some information from the official website, 1.list of all the ServiceComb features, including descriptions of all features, specifications, usage guide, demo links, and so on.
2.quick start guide, including the simplest "hello world" case, an entry-level composite microservice case (just like bmi now), a microservice case based on business scenarios, and so on.
3.FAQ, including the common problems and solutions, and each FAQ requires a clear context.
4.Summary architecture design graph, including architecture and surrounding open source ecological construction.
5.Module dependency graph of ServiceComb, the roles and dependencies of each package in the ServiceComb source code.
6.roadmap.
2018-05-11 11:52 GMT+08:00 Zen Lin <ze...@gmail.com>:
> Yeah,
>
> But I think maybe we have some misunderstanding between API-reference
> and user-guide, let us make it more clearly.
>
> To user-guide, it is a list of quckstart samples to each
> functionality of ServiecComb, such as,
> https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fclou
> d.spring.io%2Fspring-cloud-gateway%2F%23quick-start&data=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=SQN8UrCq0Qo%2BmZxlIaEgLYrXMj%2F4F9%2FXLanV2Vy8P%2Bk%3D&reserved=0 shows users how to quickly start with a gateway.
> These user guide samples can help users to quickly start from a simple
> sample to use functionality in there first step, thus can give users
> confidence and interesting to use ServiceComb.
>
> I think what Liubao is doing is just a API-reference, which is used
> for deep leaning users to use and develop ServiceComb, it is also
> important and strong required.
>
> @Willem, Liubao,
> Do you agree with the relationship between userguide and
> api-reference, if it is agreed, I think maybe Kirin can create two
> issues on JIRA, one is improvement quickstart of ServiceComb, the
> other is improvement of userguide.
>
> Best Regards,
> ---
> Zen Lin
> zenlintechnofreak@gmail.com
> Focused on Micro Service and Apache ServiceComb
>
> 2018-05-11 11:07 GMT+08:00 Willem Jiang <wi...@gmail.com>:
>
> > We could create some JIRAs to track the document relate issues.
> > @Liubao, Do you mind create some sub tasks for it?
> >
> > I think we already have some docs for the quick start and user
> > guide,
> but
> > we need to publish the API documents as well.
> > So I just fill a JIRA[1] for java-chassis and Saga about it.
> >
> > [1]https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2
> > Fissues.apache.org%2Fjira%2Fbrowse%2FSCB-575&data=02%7C01%7C%7C87535
> > 42272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7
> > C0%7C636617361648441558&sdata=iD7G9XztEJUlzjWOM2AP9fVA5e1DxxM9WoSUY4
> > D6RAw%3D&reserved=0
> >
> >
> > Willem Jiang
> >
> > Blog: https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwillemjiang.blogspot.com&data=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=zX2KgE5mGDMmenL11IC7g%2FdX78Kqj8jMkWRPr1xpm5E%3D&reserved=0 (English)
> >
> > https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fjnn
> > .iteye.com&data=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df
> > 9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=tLW0
> > 5WUrR08w1gbBU3UKXmT8ulP1q5h3XkruaY%2FrSr8%3D&reserved=0 (Chinese)
> > Twitter: willemjiang
> > Weibo: 姜宁willem
> >
> > On Fri, May 11, 2018 at 10:37 AM, Zen Lin
> > <ze...@gmail.com>
> > wrote:
> >
> > > Yeah, Nice.
> > > Hi Liubao, Kirin,
> > >
> > > I think it is better to have some detail discussion between both
> > > of you
> > to
> > > ensure a new set of document can give users a friendly and
> > > three-dimensional experience, includes quick start, user guide,
> > > API reference.
> > >
> > > Best Regards,
> > > ---
> > > Zen Lin
> > > zenlintechnofreak@gmail.com
> > > Focused on Micro Service and Apache ServiceComb
> > >
> > > 2018-05-11 9:31 GMT+08:00 bismy <bi...@qq.com>:
> > >
> > > > We are keeping in thinking a way to better guide the first start
> users.
> > > > Maybe a working project is very good start point.
> > > > However, quick start to tell the basics is also very important.
> > > > Inspired by working project, I write a quick start to let users
> > download
> > > > examples or using archetypes recently provided.
> > > > Please check
> > > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%
> > > > 2Fhuaweicse.github.io%2F&data=02%7C01%7C%7C8753542272254a277e3c0
> > > > 8d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C6366173
> > > > 61648441558&sdata=fjs6S9Dqdz6L2tthPTSFt3JsVShP5lwASBY0bmS2LiY%3D
> > > > &reserved=0
> servicecomb-java-chassis-doc/
> > > > zh_CN/start/first-sample.html
> > > >
> > > >
> > > > We are now working on better ServiceComb-java-chassis documents
> > > > now,
> > and
> > > > this link is the preview version.
> > > >
> > > >
> > > > ------------------ 原始邮件 ------------------
> > > > 发件人: "Zen Lin"<ze...@gmail.com>;
> > > > 发送时间: 2018年5月10日(星期四) 晚上7:39
> > > > 收件人: "dev"<de...@servicecomb.apache.org>;
> > > >
> > > > 主题: Re: [Discussion] Improve documents of serviceComb
> > > >
> > > >
> > > >
> > > > Hi kirin,
> > > >
> > > > Thanks.
> > > > I think we should figure out what the users want when they want
> > > > to
> > > reading
> > > > the quickstart and userguide.
> > > >
> > > > What liubao doing is to output a comprehensive user guide like
> > > > Api-reference book, and the community lacks of documentation
> > > > focused solely on helping users get started.
> > > >
> > > > I think it is quite important to supplement this deficiency, so
> > > > is
> our
> > > goal
> > > > should be focused on the following 3 key points?
> > > > 1. One simplest sample to show easily Using ServiceComb by one-click.
> > > > 2. One small sample to show users can make there apps easily
> > > > have
> basic
> > > > service governance capabilities with ServiceComb.
> > > > 3. A simple sample corresponding to a functionality of
> > > > ServiceComb,
> > like
> > > > what you mentioned like Spring.
> > > >
> > > > Anyway, you can also finding some place on the website to list
> > > > and
> > brief
> > > > introduce the medium-sized code case, like company,Weather
> > forecast，CRM.
> > > >
> > > >
> > > >
> > > > Best Regards,
> > > > ---
> > > > Zen Lin
> > > > zenlintechnofreak@gmail.com
> > > > Focused on Micro Service and Apache ServiceComb
> > > >
> > > > 2018-05-10 17:50 GMT+08:00 kirin wang <wa...@gmail.com>:
> > > >
> > > > > Hi Community：
> > > > >
> > > > > Recently we have recieved some feedback from our user
> > > > > ,
> that
> > > our
> > > > > documents are not enough quick&clear and sometimes it still
> > > > > causes
> > some
> > > > > error. May be we should discuss how to improve it together.
> > > > >
> > > > > Take our "Quick Start" as an example[1]:
> > > > > 1. Codes or configs (like "pom.xml" ) are fragment , not the
> whole
> > > file
> > > > > , some beginners cannot fully understand how to make it work .
> > > > > 2. We introduced several features like load balance, circuit
> break
> > > etc.
> > > > > Currently there are all "under bmi" , which means if one wants
> > > > > to
> > > simply
> > > > > test one of our feature, he must learn from start. Here we
> > > > > may
> > > > reference
> > > > > the docs in spring.io[2] , every feature in it can run
> > > > > separately
> > and
> > > > > quickly.
> > > > > 3. Now we already have "scaffold" aims to make developing
> > > microservices
> > > > > via serviceComb more quickly，may be it's necessary to consider
> > > integrate
> > > > > “scaffold” with current "Quick Start"
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > > [1]
> > > > > https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F
> > > > > %2Fservicecomb.incubator.apache.org%2Fdocs%2Fquick-start%2F&da
> > > > > ta=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f
> > > > > 640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=7cCe7
> > > > > 2n%2B74tofpDw%2Fe7MocQ4LBy%2FK4OEx0etGeqtLho%3D&reserved=0
> > > > > [2]
> > > > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2
> > > > > F%2Fspring.io%2Fguides&data=02%7C01%7C%7C8753542272254a277e3c0
> > > > > 8d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C63661
> > > > > 7361648441558&sdata=8YiLbK3A%2FnXcpTW8R9S3WqUDMC7uNOfghGEqJSfK
> > > > > szc%3D&reserved=0
> > > > >
> > > >
> > >
> >
>
Re: 答复: [Discussion] Improve documents of serviceComb
Posted by Zen Lin <ze...@gmail.com>.
Hi Willem ,
I am not sure weather the user guide document you mentioned here is what
Liubao is dealing with.
If it is, I think it is really nice to host it in a new git repo.
Best Regards,
---
Zen Lin
zenlintechnofreak@gmail.com
Focused on Micro Service and Apache ServiceComb
2018-05-17 16:51 GMT+08:00 Willem Jiang <wi...@gmail.com>:
> It looks like we need a new git repo to host the user guide document.
> Maybe we should start a vote for it, if we are OK for that, we could
> create new doc repo for it.
>
>
> Willem Jiang
>
> Blog: http://willemjiang.blogspot.com (English)
> http://jnn.iteye.com (Chinese)
> Twitter: willemjiang
> Weibo: 姜宁willem
>
> On Mon, May 14, 2018 at 9:56 AM, bismy <bi...@qq.com> wrote:
>
> > We have give a lot quite important suggestions, now we have to put it in
> a
> > practical way.
> >
> >
> > I suggestion we first merge what we have into the master branch and
> > anybody can create issue or submit PR's if they think
> > something need to be changed. Anyway, we need to have review the contents
> > to see which is better.
> >
> >
> > Now we can focus on two types of documents, quick start user guide and a
> > comprehensive reference guide. We can put them in one doc
> > or separate them in servicecomb website and java-chassis doc.
> >
> >
> > Anyway, we first need more great contents, then we can think of
> delivering
> > them to users better.
> >
> >
> > ------------------ 原始邮件 ------------------
> > 发件人: "JICHUN LIU"<jl...@hotmail.com>;
> > 发送时间: 2018年5月13日(星期天) 上午10:17
> > 收件人: "dev@servicecomb.apache.org"<de...@servicecomb.apache.org>;
> >
> > 主题: 答复: [Discussion] Improve documents of serviceComb
> >
> >
> >
> > Maybe we can learn sth. from the document of Spring Cloud and Vue. Both
> > have a lot of experience on document, usage guide and demos.
> >
> > -----邮件原件-----
> > 发件人: Bin Ma <ma...@gmail.com>
> > 发送时间: 2018年5月12日 23:36
> > 收件人: dev@servicecomb.apache.org
> > 主题: Re: [Discussion] Improve documents of serviceComb
> >
> > Personally, if I was a user of the first contact with ServiceComb, I
> would
> > like to get some information from the official website, 1.list of all the
> > ServiceComb features, including descriptions of all features,
> > specifications, usage guide, demo links, and so on.
> > 2.quick start guide, including the simplest "hello world" case, an
> > entry-level composite microservice case (just like bmi now), a
> microservice
> > case based on business scenarios, and so on.
> > 3.FAQ, including the common problems and solutions, and each FAQ requires
> > a clear context.
> > 4.Summary architecture design graph, including architecture and
> > surrounding open source ecological construction.
> > 5.Module dependency graph of ServiceComb, the roles and dependencies of
> > each package in the ServiceComb source code.
> > 6.roadmap.
> >
> > 2018-05-11 11:52 GMT+08:00 Zen Lin <ze...@gmail.com>:
> >
> > > Yeah,
> > >
> > > But I think maybe we have some misunderstanding between API-reference
> > > and user-guide, let us make it more clearly.
> > >
> > > To user-guide, it is a list of quckstart samples to each
> > > functionality of ServiecComb, such as,
> > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fclou
> > > d.spring.io%2Fspring-cloud-gateway%2F%23quick-start&data=02%7C01%7C%
> > 7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaa
> > aaaa%7C1%7C0%7C636617361648441558&sdata=SQN8UrCq0Qo%2BmZxlIaEgLYrXMj%
> > 2F4F9%2FXLanV2Vy8P%2Bk%3D&reserved=0 shows users how to quickly start
> > with a gateway.
> > > These user guide samples can help users to quickly start from a simple
> > > sample to use functionality in there first step, thus can give users
> > > confidence and interesting to use ServiceComb.
> > >
> > > I think what Liubao is doing is just a API-reference, which is used
> > > for deep leaning users to use and develop ServiceComb, it is also
> > > important and strong required.
> > >
> > > @Willem, Liubao,
> > > Do you agree with the relationship between userguide and
> > > api-reference, if it is agreed, I think maybe Kirin can create two
> > > issues on JIRA, one is improvement quickstart of ServiceComb, the
> > > other is improvement of userguide.
> > >
> > > Best Regards,
> > > ---
> > > Zen Lin
> > > zenlintechnofreak@gmail.com
> > > Focused on Micro Service and Apache ServiceComb
> > >
> > > 2018-05-11 11:07 GMT+08:00 Willem Jiang <wi...@gmail.com>:
> > >
> > > > We could create some JIRAs to track the document relate issues.
> > > > @Liubao, Do you mind create some sub tasks for it?
> > > >
> > > > I think we already have some docs for the quick start and user
> > > > guide,
> > > but
> > > > we need to publish the API documents as well.
> > > > So I just fill a JIRA[1] for java-chassis and Saga about it.
> > > >
> > > > [1]https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2
> > > > Fissues.apache.org%2Fjira%2Fbrowse%2FSCB-575&data=02%7C01%7C%7C87535
> > > > 42272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7
> > > > C0%7C636617361648441558&sdata=iD7G9XztEJUlzjWOM2AP9fVA5e1DxxM9WoSUY4
> > > > D6RAw%3D&reserved=0
> > > >
> > > >
> > > > Willem Jiang
> > > >
> > > > Blog: https://eur02.safelinks.protection.outlook.com/?url=
> > http%3A%2F%2Fwillemjiang.blogspot.com&data=02%7C01%7C%
> > 7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaa
> > aaaa%7C1%7C0%7C636617361648441558&sdata=zX2KgE5mGDMmenL11IC7g%
> > 2FdX78Kqj8jMkWRPr1xpm5E%3D&reserved=0 (English)
> > > >
> > > > https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fjnn
> > > > .iteye.com&data=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df
> > > > 9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=tLW0
> > > > 5WUrR08w1gbBU3UKXmT8ulP1q5h3XkruaY%2FrSr8%3D&reserved=0 (Chinese)
> > > > Twitter: willemjiang
> > > > Weibo: 姜宁willem
> > > >
> > > > On Fri, May 11, 2018 at 10:37 AM, Zen Lin
> > > > <ze...@gmail.com>
> > > > wrote:
> > > >
> > > > > Yeah, Nice.
> > > > > Hi Liubao, Kirin,
> > > > >
> > > > > I think it is better to have some detail discussion between both
> > > > > of you
> > > > to
> > > > > ensure a new set of document can give users a friendly and
> > > > > three-dimensional experience, includes quick start, user guide,
> > > > > API reference.
> > > > >
> > > > > Best Regards,
> > > > > ---
> > > > > Zen Lin
> > > > > zenlintechnofreak@gmail.com
> > > > > Focused on Micro Service and Apache ServiceComb
> > > > >
> > > > > 2018-05-11 9:31 GMT+08:00 bismy <bi...@qq.com>:
> > > > >
> > > > > > We are keeping in thinking a way to better guide the first start
> > > users.
> > > > > > Maybe a working project is very good start point.
> > > > > > However, quick start to tell the basics is also very important.
> > > > > > Inspired by working project, I write a quick start to let users
> > > > download
> > > > > > examples or using archetypes recently provided.
> > > > > > Please check
> > > > > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%
> > > > > > 2Fhuaweicse.github.io%2F&data=02%7C01%7C%7C8753542272254a277e3c0
> > > > > > 8d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C6366173
> > > > > > 61648441558&sdata=fjs6S9Dqdz6L2tthPTSFt3JsVShP5lwASBY0bmS2LiY%3D
> > > > > > &reserved=0
> > > servicecomb-java-chassis-doc/
> > > > > > zh_CN/start/first-sample.html
> > > > > >
> > > > > >
> > > > > > We are now working on better ServiceComb-java-chassis documents
> > > > > > now,
> > > > and
> > > > > > this link is the preview version.
> > > > > >
> > > > > >
> > > > > > ------------------ 原始邮件 ------------------
> > > > > > 发件人: "Zen Lin"<ze...@gmail.com>;
> > > > > > 发送时间: 2018年5月10日(星期四) 晚上7:39
> > > > > > 收件人: "dev"<de...@servicecomb.apache.org>;
> > > > > >
> > > > > > 主题: Re: [Discussion] Improve documents of serviceComb
> > > > > >
> > > > > >
> > > > > >
> > > > > > Hi kirin,
> > > > > >
> > > > > > Thanks.
> > > > > > I think we should figure out what the users want when they want
> > > > > > to
> > > > > reading
> > > > > > the quickstart and userguide.
> > > > > >
> > > > > > What liubao doing is to output a comprehensive user guide like
> > > > > > Api-reference book, and the community lacks of documentation
> > > > > > focused solely on helping users get started.
> > > > > >
> > > > > > I think it is quite important to supplement this deficiency, so
> > > > > > is
> > > our
> > > > > goal
> > > > > > should be focused on the following 3 key points?
> > > > > > 1. One simplest sample to show easily Using ServiceComb by
> > one-click.
> > > > > > 2. One small sample to show users can make there apps easily
> > > > > > have
> > > basic
> > > > > > service governance capabilities with ServiceComb.
> > > > > > 3. A simple sample corresponding to a functionality of
> > > > > > ServiceComb,
> > > > like
> > > > > > what you mentioned like Spring.
> > > > > >
> > > > > > Anyway, you can also finding some place on the website to list
> > > > > > and
> > > > brief
> > > > > > introduce the medium-sized code case, like company,Weather
> > > > forecast，CRM.
> > > > > >
> > > > > >
> > > > > >
> > > > > > Best Regards,
> > > > > > ---
> > > > > > Zen Lin
> > > > > > zenlintechnofreak@gmail.com
> > > > > > Focused on Micro Service and Apache ServiceComb
> > > > > >
> > > > > > 2018-05-10 17:50 GMT+08:00 kirin wang <wa...@gmail.com>:
> > > > > >
> > > > > > > Hi Community：
> > > > > > >
> > > > > > > Recently we have recieved some feedback from our user
> > > > > > > ,
> > > that
> > > > > our
> > > > > > > documents are not enough quick&clear and sometimes it still
> > > > > > > causes
> > > > some
> > > > > > > error. May be we should discuss how to improve it together.
> > > > > > >
> > > > > > > Take our "Quick Start" as an example[1]:
> > > > > > > 1. Codes or configs (like "pom.xml" ) are fragment , not the
> > > whole
> > > > > file
> > > > > > > , some beginners cannot fully understand how to make it work .
> > > > > > > 2. We introduced several features like load balance, circuit
> > > break
> > > > > etc.
> > > > > > > Currently there are all "under bmi" , which means if one wants
> > > > > > > to
> > > > > simply
> > > > > > > test one of our feature, he must learn from start. Here we
> > > > > > > may
> > > > > > reference
> > > > > > > the docs in spring.io[2] , every feature in it can run
> > > > > > > separately
> > > > and
> > > > > > > quickly.
> > > > > > > 3. Now we already have "scaffold" aims to make developing
> > > > > microservices
> > > > > > > via serviceComb more quickly，may be it's necessary to consider
> > > > > integrate
> > > > > > > “scaffold” with current "Quick Start"
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > [1]
> > > > > > > https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F
> > > > > > > %2Fservicecomb.incubator.apache.org%2Fdocs%2Fquick-start%2F&da
> > > > > > > ta=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f
> > > > > > > 640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=7cCe7
> > > > > > > 2n%2B74tofpDw%2Fe7MocQ4LBy%2FK4OEx0etGeqtLho%3D&reserved=0
> > > > > > > [2]
> > > > > > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2
> > > > > > > F%2Fspring.io%2Fguides&data=02%7C01%7C%7C8753542272254a277e3c0
> > > > > > > 8d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C63661
> > > > > > > 7361648441558&sdata=8YiLbK3A%2FnXcpTW8R9S3WqUDMC7uNOfghGEqJSfK
> > > > > > > szc%3D&reserved=0
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: 答复: [Discussion] Improve documents of serviceComb
Posted by Willem Jiang <wi...@gmail.com>.
It looks like we need a new git repo to host the user guide document.
Maybe we should start a vote for it, if we are OK for that, we could
create new doc repo for it.
Willem Jiang
Blog: http://willemjiang.blogspot.com (English)
http://jnn.iteye.com (Chinese)
Twitter: willemjiang
Weibo: 姜宁willem
On Mon, May 14, 2018 at 9:56 AM, bismy <bi...@qq.com> wrote:
> We have give a lot quite important suggestions, now we have to put it in a
> practical way.
>
>
> I suggestion we first merge what we have into the master branch and
> anybody can create issue or submit PR's if they think
> something need to be changed. Anyway, we need to have review the contents
> to see which is better.
>
>
> Now we can focus on two types of documents, quick start user guide and a
> comprehensive reference guide. We can put them in one doc
> or separate them in servicecomb website and java-chassis doc.
>
>
> Anyway, we first need more great contents, then we can think of delivering
> them to users better.
>
>
> ------------------ 原始邮件 ------------------
> 发件人: "JICHUN LIU"<jl...@hotmail.com>;
> 发送时间: 2018年5月13日(星期天) 上午10:17
> 收件人: "dev@servicecomb.apache.org"<de...@servicecomb.apache.org>;
>
> 主题: 答复: [Discussion] Improve documents of serviceComb
>
>
>
> Maybe we can learn sth. from the document of Spring Cloud and Vue. Both
> have a lot of experience on document, usage guide and demos.
>
> -----邮件原件-----
> 发件人: Bin Ma <ma...@gmail.com>
> 发送时间: 2018年5月12日 23:36
> 收件人: dev@servicecomb.apache.org
> 主题: Re: [Discussion] Improve documents of serviceComb
>
> Personally, if I was a user of the first contact with ServiceComb, I would
> like to get some information from the official website, 1.list of all the
> ServiceComb features, including descriptions of all features,
> specifications, usage guide, demo links, and so on.
> 2.quick start guide, including the simplest "hello world" case, an
> entry-level composite microservice case (just like bmi now), a microservice
> case based on business scenarios, and so on.
> 3.FAQ, including the common problems and solutions, and each FAQ requires
> a clear context.
> 4.Summary architecture design graph, including architecture and
> surrounding open source ecological construction.
> 5.Module dependency graph of ServiceComb, the roles and dependencies of
> each package in the ServiceComb source code.
> 6.roadmap.
>
> 2018-05-11 11:52 GMT+08:00 Zen Lin <ze...@gmail.com>:
>
> > Yeah,
> >
> > But I think maybe we have some misunderstanding between API-reference
> > and user-guide, let us make it more clearly.
> >
> > To user-guide, it is a list of quckstart samples to each
> > functionality of ServiecComb, such as,
> > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fclou
> > d.spring.io%2Fspring-cloud-gateway%2F%23quick-start&data=02%7C01%7C%
> 7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaa
> aaaa%7C1%7C0%7C636617361648441558&sdata=SQN8UrCq0Qo%2BmZxlIaEgLYrXMj%
> 2F4F9%2FXLanV2Vy8P%2Bk%3D&reserved=0 shows users how to quickly start
> with a gateway.
> > These user guide samples can help users to quickly start from a simple
> > sample to use functionality in there first step, thus can give users
> > confidence and interesting to use ServiceComb.
> >
> > I think what Liubao is doing is just a API-reference, which is used
> > for deep leaning users to use and develop ServiceComb, it is also
> > important and strong required.
> >
> > @Willem, Liubao,
> > Do you agree with the relationship between userguide and
> > api-reference, if it is agreed, I think maybe Kirin can create two
> > issues on JIRA, one is improvement quickstart of ServiceComb, the
> > other is improvement of userguide.
> >
> > Best Regards,
> > ---
> > Zen Lin
> > zenlintechnofreak@gmail.com
> > Focused on Micro Service and Apache ServiceComb
> >
> > 2018-05-11 11:07 GMT+08:00 Willem Jiang <wi...@gmail.com>:
> >
> > > We could create some JIRAs to track the document relate issues.
> > > @Liubao, Do you mind create some sub tasks for it?
> > >
> > > I think we already have some docs for the quick start and user
> > > guide,
> > but
> > > we need to publish the API documents as well.
> > > So I just fill a JIRA[1] for java-chassis and Saga about it.
> > >
> > > [1]https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2
> > > Fissues.apache.org%2Fjira%2Fbrowse%2FSCB-575&data=02%7C01%7C%7C87535
> > > 42272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7
> > > C0%7C636617361648441558&sdata=iD7G9XztEJUlzjWOM2AP9fVA5e1DxxM9WoSUY4
> > > D6RAw%3D&reserved=0
> > >
> > >
> > > Willem Jiang
> > >
> > > Blog: https://eur02.safelinks.protection.outlook.com/?url=
> http%3A%2F%2Fwillemjiang.blogspot.com&data=02%7C01%7C%
> 7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaa
> aaaa%7C1%7C0%7C636617361648441558&sdata=zX2KgE5mGDMmenL11IC7g%
> 2FdX78Kqj8jMkWRPr1xpm5E%3D&reserved=0 (English)
> > >
> > > https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fjnn
> > > .iteye.com&data=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df
> > > 9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=tLW0
> > > 5WUrR08w1gbBU3UKXmT8ulP1q5h3XkruaY%2FrSr8%3D&reserved=0 (Chinese)
> > > Twitter: willemjiang
> > > Weibo: 姜宁willem
> > >
> > > On Fri, May 11, 2018 at 10:37 AM, Zen Lin
> > > <ze...@gmail.com>
> > > wrote:
> > >
> > > > Yeah, Nice.
> > > > Hi Liubao, Kirin,
> > > >
> > > > I think it is better to have some detail discussion between both
> > > > of you
> > > to
> > > > ensure a new set of document can give users a friendly and
> > > > three-dimensional experience, includes quick start, user guide,
> > > > API reference.
> > > >
> > > > Best Regards,
> > > > ---
> > > > Zen Lin
> > > > zenlintechnofreak@gmail.com
> > > > Focused on Micro Service and Apache ServiceComb
> > > >
> > > > 2018-05-11 9:31 GMT+08:00 bismy <bi...@qq.com>:
> > > >
> > > > > We are keeping in thinking a way to better guide the first start
> > users.
> > > > > Maybe a working project is very good start point.
> > > > > However, quick start to tell the basics is also very important.
> > > > > Inspired by working project, I write a quick start to let users
> > > download
> > > > > examples or using archetypes recently provided.
> > > > > Please check
> > > > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%
> > > > > 2Fhuaweicse.github.io%2F&data=02%7C01%7C%7C8753542272254a277e3c0
> > > > > 8d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C6366173
> > > > > 61648441558&sdata=fjs6S9Dqdz6L2tthPTSFt3JsVShP5lwASBY0bmS2LiY%3D
> > > > > &reserved=0
> > servicecomb-java-chassis-doc/
> > > > > zh_CN/start/first-sample.html
> > > > >
> > > > >
> > > > > We are now working on better ServiceComb-java-chassis documents
> > > > > now,
> > > and
> > > > > this link is the preview version.
> > > > >
> > > > >
> > > > > ------------------ 原始邮件 ------------------
> > > > > 发件人: "Zen Lin"<ze...@gmail.com>;
> > > > > 发送时间: 2018年5月10日(星期四) 晚上7:39
> > > > > 收件人: "dev"<de...@servicecomb.apache.org>;
> > > > >
> > > > > 主题: Re: [Discussion] Improve documents of serviceComb
> > > > >
> > > > >
> > > > >
> > > > > Hi kirin,
> > > > >
> > > > > Thanks.
> > > > > I think we should figure out what the users want when they want
> > > > > to
> > > > reading
> > > > > the quickstart and userguide.
> > > > >
> > > > > What liubao doing is to output a comprehensive user guide like
> > > > > Api-reference book, and the community lacks of documentation
> > > > > focused solely on helping users get started.
> > > > >
> > > > > I think it is quite important to supplement this deficiency, so
> > > > > is
> > our
> > > > goal
> > > > > should be focused on the following 3 key points?
> > > > > 1. One simplest sample to show easily Using ServiceComb by
> one-click.
> > > > > 2. One small sample to show users can make there apps easily
> > > > > have
> > basic
> > > > > service governance capabilities with ServiceComb.
> > > > > 3. A simple sample corresponding to a functionality of
> > > > > ServiceComb,
> > > like
> > > > > what you mentioned like Spring.
> > > > >
> > > > > Anyway, you can also finding some place on the website to list
> > > > > and
> > > brief
> > > > > introduce the medium-sized code case, like company,Weather
> > > forecast，CRM.
> > > > >
> > > > >
> > > > >
> > > > > Best Regards,
> > > > > ---
> > > > > Zen Lin
> > > > > zenlintechnofreak@gmail.com
> > > > > Focused on Micro Service and Apache ServiceComb
> > > > >
> > > > > 2018-05-10 17:50 GMT+08:00 kirin wang <wa...@gmail.com>:
> > > > >
> > > > > > Hi Community：
> > > > > >
> > > > > > Recently we have recieved some feedback from our user
> > > > > > ,
> > that
> > > > our
> > > > > > documents are not enough quick&clear and sometimes it still
> > > > > > causes
> > > some
> > > > > > error. May be we should discuss how to improve it together.
> > > > > >
> > > > > > Take our "Quick Start" as an example[1]:
> > > > > > 1. Codes or configs (like "pom.xml" ) are fragment , not the
> > whole
> > > > file
> > > > > > , some beginners cannot fully understand how to make it work .
> > > > > > 2. We introduced several features like load balance, circuit
> > break
> > > > etc.
> > > > > > Currently there are all "under bmi" , which means if one wants
> > > > > > to
> > > > simply
> > > > > > test one of our feature, he must learn from start. Here we
> > > > > > may
> > > > > reference
> > > > > > the docs in spring.io[2] , every feature in it can run
> > > > > > separately
> > > and
> > > > > > quickly.
> > > > > > 3. Now we already have "scaffold" aims to make developing
> > > > microservices
> > > > > > via serviceComb more quickly，may be it's necessary to consider
> > > > integrate
> > > > > > “scaffold” with current "Quick Start"
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > [1]
> > > > > > https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F
> > > > > > %2Fservicecomb.incubator.apache.org%2Fdocs%2Fquick-start%2F&da
> > > > > > ta=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f
> > > > > > 640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=7cCe7
> > > > > > 2n%2B74tofpDw%2Fe7MocQ4LBy%2FK4OEx0etGeqtLho%3D&reserved=0
> > > > > > [2]
> > > > > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2
> > > > > > F%2Fspring.io%2Fguides&data=02%7C01%7C%7C8753542272254a277e3c0
> > > > > > 8d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C63661
> > > > > > 7361648441558&sdata=8YiLbK3A%2FnXcpTW8R9S3WqUDMC7uNOfghGEqJSfK
> > > > > > szc%3D&reserved=0
> > > > > >
> > > > >
> > > >
> > >
> >
>
回复：答复: [Discussion] Improve documents of serviceComb
Posted by bismy <bi...@qq.com>.
We have give a lot quite important suggestions, now we have to put it in a practical way.
I suggestion we first merge what we have into the master branch and anybody can create issue or submit PR's if they think
something need to be changed. Anyway, we need to have review the contents to see which is better.
Now we can focus on two types of documents, quick start user guide and a comprehensive reference guide. We can put them in one doc
or separate them in servicecomb website and java-chassis doc.
Anyway, we first need more great contents, then we can think of delivering them to users better.
------------------ 原始邮件 ------------------
发件人: "JICHUN LIU"<jl...@hotmail.com>;
发送时间: 2018年5月13日(星期天) 上午10:17
收件人: "dev@servicecomb.apache.org"<de...@servicecomb.apache.org>;
主题: 答复: [Discussion] Improve documents of serviceComb
Maybe we can learn sth. from the document of Spring Cloud and Vue. Both have a lot of experience on document, usage guide and demos.
-----邮件原件-----
发件人: Bin Ma <ma...@gmail.com>
发送时间: 2018年5月12日 23:36
收件人: dev@servicecomb.apache.org
主题: Re: [Discussion] Improve documents of serviceComb
Personally, if I was a user of the first contact with ServiceComb, I would like to get some information from the official website, 1.list of all the ServiceComb features, including descriptions of all features, specifications, usage guide, demo links, and so on.
2.quick start guide, including the simplest "hello world" case, an entry-level composite microservice case (just like bmi now), a microservice case based on business scenarios, and so on.
3.FAQ, including the common problems and solutions, and each FAQ requires a clear context.
4.Summary architecture design graph, including architecture and surrounding open source ecological construction.
5.Module dependency graph of ServiceComb, the roles and dependencies of each package in the ServiceComb source code.
6.roadmap.
2018-05-11 11:52 GMT+08:00 Zen Lin <ze...@gmail.com>:
> Yeah,
>
> But I think maybe we have some misunderstanding between API-reference
> and user-guide, let us make it more clearly.
>
> To user-guide, it is a list of quckstart samples to each
> functionality of ServiecComb, such as,
> https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fclou
> d.spring.io%2Fspring-cloud-gateway%2F%23quick-start&data=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=SQN8UrCq0Qo%2BmZxlIaEgLYrXMj%2F4F9%2FXLanV2Vy8P%2Bk%3D&reserved=0 shows users how to quickly start with a gateway.
> These user guide samples can help users to quickly start from a simple
> sample to use functionality in there first step, thus can give users
> confidence and interesting to use ServiceComb.
>
> I think what Liubao is doing is just a API-reference, which is used
> for deep leaning users to use and develop ServiceComb, it is also
> important and strong required.
>
> @Willem, Liubao,
> Do you agree with the relationship between userguide and
> api-reference, if it is agreed, I think maybe Kirin can create two
> issues on JIRA, one is improvement quickstart of ServiceComb, the
> other is improvement of userguide.
>
> Best Regards,
> ---
> Zen Lin
> zenlintechnofreak@gmail.com
> Focused on Micro Service and Apache ServiceComb
>
> 2018-05-11 11:07 GMT+08:00 Willem Jiang <wi...@gmail.com>:
>
> > We could create some JIRAs to track the document relate issues.
> > @Liubao, Do you mind create some sub tasks for it?
> >
> > I think we already have some docs for the quick start and user
> > guide,
> but
> > we need to publish the API documents as well.
> > So I just fill a JIRA[1] for java-chassis and Saga about it.
> >
> > [1]https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2
> > Fissues.apache.org%2Fjira%2Fbrowse%2FSCB-575&data=02%7C01%7C%7C87535
> > 42272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7
> > C0%7C636617361648441558&sdata=iD7G9XztEJUlzjWOM2AP9fVA5e1DxxM9WoSUY4
> > D6RAw%3D&reserved=0
> >
> >
> > Willem Jiang
> >
> > Blog: https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwillemjiang.blogspot.com&data=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=zX2KgE5mGDMmenL11IC7g%2FdX78Kqj8jMkWRPr1xpm5E%3D&reserved=0 (English)
> >
> > https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fjnn
> > .iteye.com&data=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df
> > 9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=tLW0
> > 5WUrR08w1gbBU3UKXmT8ulP1q5h3XkruaY%2FrSr8%3D&reserved=0 (Chinese)
> > Twitter: willemjiang
> > Weibo: 姜宁willem
> >
> > On Fri, May 11, 2018 at 10:37 AM, Zen Lin
> > <ze...@gmail.com>
> > wrote:
> >
> > > Yeah, Nice.
> > > Hi Liubao, Kirin,
> > >
> > > I think it is better to have some detail discussion between both
> > > of you
> > to
> > > ensure a new set of document can give users a friendly and
> > > three-dimensional experience, includes quick start, user guide,
> > > API reference.
> > >
> > > Best Regards,
> > > ---
> > > Zen Lin
> > > zenlintechnofreak@gmail.com
> > > Focused on Micro Service and Apache ServiceComb
> > >
> > > 2018-05-11 9:31 GMT+08:00 bismy <bi...@qq.com>:
> > >
> > > > We are keeping in thinking a way to better guide the first start
> users.
> > > > Maybe a working project is very good start point.
> > > > However, quick start to tell the basics is also very important.
> > > > Inspired by working project, I write a quick start to let users
> > download
> > > > examples or using archetypes recently provided.
> > > > Please check
> > > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%
> > > > 2Fhuaweicse.github.io%2F&data=02%7C01%7C%7C8753542272254a277e3c0
> > > > 8d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C6366173
> > > > 61648441558&sdata=fjs6S9Dqdz6L2tthPTSFt3JsVShP5lwASBY0bmS2LiY%3D
> > > > &reserved=0
> servicecomb-java-chassis-doc/
> > > > zh_CN/start/first-sample.html
> > > >
> > > >
> > > > We are now working on better ServiceComb-java-chassis documents
> > > > now,
> > and
> > > > this link is the preview version.
> > > >
> > > >
> > > > ------------------ 原始邮件 ------------------
> > > > 发件人: "Zen Lin"<ze...@gmail.com>;
> > > > 发送时间: 2018年5月10日(星期四) 晚上7:39
> > > > 收件人: "dev"<de...@servicecomb.apache.org>;
> > > >
> > > > 主题: Re: [Discussion] Improve documents of serviceComb
> > > >
> > > >
> > > >
> > > > Hi kirin,
> > > >
> > > > Thanks.
> > > > I think we should figure out what the users want when they want
> > > > to
> > > reading
> > > > the quickstart and userguide.
> > > >
> > > > What liubao doing is to output a comprehensive user guide like
> > > > Api-reference book, and the community lacks of documentation
> > > > focused solely on helping users get started.
> > > >
> > > > I think it is quite important to supplement this deficiency, so
> > > > is
> our
> > > goal
> > > > should be focused on the following 3 key points?
> > > > 1. One simplest sample to show easily Using ServiceComb by one-click.
> > > > 2. One small sample to show users can make there apps easily
> > > > have
> basic
> > > > service governance capabilities with ServiceComb.
> > > > 3. A simple sample corresponding to a functionality of
> > > > ServiceComb,
> > like
> > > > what you mentioned like Spring.
> > > >
> > > > Anyway, you can also finding some place on the website to list
> > > > and
> > brief
> > > > introduce the medium-sized code case, like company,Weather
> > forecast，CRM.
> > > >
> > > >
> > > >
> > > > Best Regards,
> > > > ---
> > > > Zen Lin
> > > > zenlintechnofreak@gmail.com
> > > > Focused on Micro Service and Apache ServiceComb
> > > >
> > > > 2018-05-10 17:50 GMT+08:00 kirin wang <wa...@gmail.com>:
> > > >
> > > > > Hi Community：
> > > > >
> > > > > Recently we have recieved some feedback from our user
> > > > > ,
> that
> > > our
> > > > > documents are not enough quick&clear and sometimes it still
> > > > > causes
> > some
> > > > > error. May be we should discuss how to improve it together.
> > > > >
> > > > > Take our "Quick Start" as an example[1]:
> > > > > 1. Codes or configs (like "pom.xml" ) are fragment , not the
> whole
> > > file
> > > > > , some beginners cannot fully understand how to make it work .
> > > > > 2. We introduced several features like load balance, circuit
> break
> > > etc.
> > > > > Currently there are all "under bmi" , which means if one wants
> > > > > to
> > > simply
> > > > > test one of our feature, he must learn from start. Here we
> > > > > may
> > > > reference
> > > > > the docs in spring.io[2] , every feature in it can run
> > > > > separately
> > and
> > > > > quickly.
> > > > > 3. Now we already have "scaffold" aims to make developing
> > > microservices
> > > > > via serviceComb more quickly，may be it's necessary to consider
> > > integrate
> > > > > “scaffold” with current "Quick Start"
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > > [1]
> > > > > https://eur02.safelinks.protection.outlook.com/?url=http%3A%2F
> > > > > %2Fservicecomb.incubator.apache.org%2Fdocs%2Fquick-start%2F&da
> > > > > ta=02%7C01%7C%7C8753542272254a277e3c08d5b81e11b5%7C84df9e7fe9f
> > > > > 640afb435aaaaaaaaaaaa%7C1%7C0%7C636617361648441558&sdata=7cCe7
> > > > > 2n%2B74tofpDw%2Fe7MocQ4LBy%2FK4OEx0etGeqtLho%3D&reserved=0
> > > > > [2]
> > > > > https://eur02.safelinks.protection.outlook.com/?url=https%3A%2
> > > > > F%2Fspring.io%2Fguides&data=02%7C01%7C%7C8753542272254a277e3c0
> > > > > 8d5b81e11b5%7C84df9e7fe9f640afb435aaaaaaaaaaaa%7C1%7C0%7C63661
> > > > > 7361648441558&sdata=8YiLbK3A%2FnXcpTW8R9S3WqUDMC7uNOfghGEqJSfK
> > > > > szc%3D&reserved=0
> > > > >
> > > >
> > >
> >
>