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://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 > > > > > > > > > > > > > > >
