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://cloud.spring.io/spring-cloud-gateway/#quick-start 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 [email protected] Focused on Micro Service and Apache ServiceComb 2018-05-11 11:07 GMT+08:00 Willem Jiang <[email protected]>: > 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://issues.apache.org/jira/browse/SCB-575 > > > Willem Jiang > > Blog: http://willemjiang.blogspot.com (English) > http://jnn.iteye.com (Chinese) > Twitter: willemjiang > Weibo: 姜宁willem > > On Fri, May 11, 2018 at 10:37 AM, Zen Lin <[email protected]> > 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 > > [email protected] > > Focused on Micro Service and Apache ServiceComb > > > > 2018-05-11 9:31 GMT+08:00 bismy <[email protected]>: > > > > > 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://huaweicse.github.io/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"<[email protected]>; > > > 发送时间: 2018年5月10日(星期四) 晚上7:39 > > > 收件人: "dev"<[email protected]>; > > > > > > 主题: 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 > > > [email protected] > > > Focused on Micro Service and Apache ServiceComb > > > > > > 2018-05-10 17:50 GMT+08:00 kirin wang <[email protected]>: > > > > > > > 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] http://servicecomb.incubator.apache.org/docs/quick-start/ > > > > [2] https://spring.io/guides > > > > > > > > > >
