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 [email protected] Focused on Micro Service and Apache ServiceComb 2018-05-17 16:51 GMT+08:00 Willem Jiang <[email protected]>: > 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 <[email protected]> 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"<[email protected]>; > > 发送时间: 2018年5月13日(星期天) 上午10:17 > > 收件人: "[email protected]"<[email protected]>; > > > > 主题: 答复: [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 <[email protected]> > > 发送时间: 2018年5月12日 23:36 > > 收件人: [email protected] > > 主题: 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 <[email protected]>: > > > > > 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 > > > [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://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 > > > > <[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://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"<[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] > > > > > > > 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 > > > > > > > > > > > > > > > > > > > > > > > > > > > >
