Documentation Workgroup: Minutes June 9th, Meeting 4B
|
Anthony O'Dowd <a_o-dowd@...>
Hyperledger Fabric Documentation Workgroup
Friday June 9, Meeting 4B
These minutes: https://drive.google.com/open?id=0B-n-iLEM1iXrdTI4Y3VSekxLeGM Time: 1600 UTC+1, e.g. 1100EDT, 0800PDT, 1200 BST, 1700 CET, 1800 RST Attendees: Anthony O’Dowd(AO), Joe Alewine(JA), Sean Barclay(SB), Raissa Xie(RX), Jeremy Anderson(JA), Sarah Mills(SM), Mark Parzygnat(MP), Tracy Kuhrt(TK), Yu Lee (Andrea)(YL), Sudip B(SB), Jeff Garratt(JG), Lucie Wu(LW), Kathryn Harrison(KH), Jason Clark (JC) Apologies: Agenda ------ 1. Reviewed the following charts: https://drive.google.com/open?id=0B-n-iLEM1iXrRXpybHBHb1RKWmM 2. Introductions from everyone to the wider team. A warm welcome to new joiners Andrea, Raissa, Kathryn and Sudip 3. Updates on current work items Thanks for keeping status up to date via mailing list. Updated items in minutes below 4. Topic Preview: Writing Your First Blockchain Application Reviewed documentation: http://fabricstaging.readthedocs.io/en/latest/write_first_app.html Led by JA. TK: Topic feels like reading the app and running the app. No code is written. Is intention to modify topic to help people write the code? JA: This isn’t included yet, as waiting for fabcar sample code. MP: Current sample is using code snippet which is not application sample code, so people can write the application. TK: Important that people can put into editor and issue commands. Needs to be interactive. AO: Feedback from Eastern hemisphere call: Writing First Application section headers didn’t flow too well. Reaffirm TK feedback - would be nicer to introduce sample earlier on with concepts, and then relate activities to sample with code at the relevant point. Tie car into more generic concepts. EM: What is relationship between car sample in Fabric and Composer? Is there a relationship between the two? AO relates to personae work: Ade is application developer who has different ways to create an application - either with Fabric or Composer. This is separate to Bala, Blockchain Administrator. Cars are good example to provide synergy between Fabric and Composer. c.f. Car Auction. SB: Needs a better transition between sections. Concepts need to flow a little better - it’s a little disjointed right now, but don’t see the payoff. Car example is nice, but needs to be better integrated as a concept into the task. How does it relate to Marbles? RX: Is documentation aimed at application developer? Are we expecting user to set up network through getting started and write tutorials afterwards. AO showed section on creating dev network. RX: Do users need to go through existing Getting Started? AO: No - this is a self contained activity. RX: Should this network be another option in getting started - what is the synergy between these two tasks? These could be better integrated MP: Would appreciate RX going through current GS. RX: Need to have coherence between getting networks up and running. MP: CF talks about the need to populate the ledger before it is queried. This needs to feature appropriately in topic: AO: Ade isn’t interested in creating a network, rather writing first application TK: Writing Application is first thing, and Running application is second thing. Are these the same tasks? Need to have Writing Application and Running Sample as integrated JA: This network is just for testing. GS has network with multiple peers. User wants to test an app against most simple network. TK: Agree - software developer doesn’t care about network. SB: Composer GS is god - need to see something in short space of time. Simple node app does that, and this sample should be the same. There seems to be a lot of complexity here. Query code looks intimidating. If it’s basic, then code needs to look basic. JA: Real sample application is shorter than this sample in the text. Can AO confirm? AO: Fabric queries and APIs in general are not single lines of code. That’s OK - these are Application Developers, who expect to write code, and burden is not excessive. MP: Good to flow car demo with Fabric and Composer - that will lead to stronger integration being car oriented. SB: Need to have more advanced samples too. For example, writing more advanced chain code/smart contracts. Need to talk about install and instantiate - this relates to CLI. How does this all relate to Writing Your First Application. Current GS is helping with this. Sudip also likes to see transaction flow to interns - it’s helpful to have this. It’s fine in architecture section, but it is important. SB: Lots of POC experience from Sudip, developed 3/4 applications, and now want to write more advanced applications. Documentation lag on multiple peer networks on local machine or in different physical environments. Lots of questions on this. Query/Invoke is different from v0.6 to v1.0, but also need to understand how to process events. How to build a custom network is also important - there needs to be topics and examples for these. AO: After First Application, these topics are really important to cover. MP: Sudip to test multi-host environment for V1.0. NG to work with Sudip. Local Hackathon means Sudip is trying this out quite a lot. MP to share with Sudip. YL: Story-telling is being used, but context and user and graphics need to relate a little better to each other. Or is a technical approach better? Need to pick one - feels a little mixed at the moment. LW: Topic needs to be higher in navigation closer to Getting Started. Need to get some tasks established earlier, e.g. setting up network.\ KH: Joining to understand little more about developer experience. JC: Very interested in multi-node configuration. Will contact MP. AO: Lots of very good input. Concerned about disconnect between proposal and topic experience. Need some work on that translation to help developer to write first application. Needs work, but still early. MP: Structure of topic needs a slight rework, per RX comments. Get network set up, and run some of the application earlier, with car context. This would help. JG: Still trying to document clearly concepts that are still emerging. Need to try things out - things are necessarily a bit ambiguous. Need to try some things. TK: Progressive disclosure is important. Start from nothing an build up. Write code in individual pieces. Lots of good stuff here, and great pieces, but need to be integrated a little better. Needs to build up to create app and then run application. This progressiveness is important, and not a lot of changes to achieve this. JA: Summarised as get the application and then build the application, then run the application. This will be easier once we have the code. JG: Stratification of roles is important. We need to focus on developer. Lots of other roles are important, but some people will be interested in these, others will not. SB: Also need high level material to introduce the concepts. Need to be conscious of infrastructure component. UI and REST APIs would be helpful on an overall picture. A working sample will help here. SM: Like indicator for how long it will take. Could incorporate into docs as a standard tag. JA: Time and Experience level are really helpful. Example is there, but story isn’t quite there. These things help new person. EM: Car commonality will help with Composer Fabric integration SB: Heading in right direction. Automate and simplify and streamline. JG: Will need to think about Administration topic, and will come up on follow-on call (AO). JAN: Agree with comments raised in general. Addressing comments will help. JA: Put car app up front and concepts referring to it. Version will be put out mid week. This will be significant next step. AO: Thanks to JA for getting first pass into code base. KH: Keep visuals, spacing, Key Concepts, try to keep this less intimidating. Much more approachable, and next iterations need to continue this progress. LW: Lots of potential, and is getting better. Incorporate comments to help with user-friendliness and intuitivevness. MP: Need to move topic along, and move into Admin role as per JG Comments. SM: Feedback mechanism into documentation to make ticket for feedback. Link with EM in Composer team SB: Will review new release of topic documentation TK: Thanks to JA for topic content. YL: Good start and keep shaping. Chat input: JC: Interested in MP sending multi-node documentation Actions +++++++ Need to incorporate this feedback into WYFA topic 5. Next meetings will be scheduled for Friday 16 June, 0600 UTC+1, 1600 UTC+1. (These are the same times as today’s meetings.) Meeting closed at 1700 UTC+1, 1200 EDT, 0900 PDT, 1300 BST, 1800 CET, 1900 RST Actions +++++++ 1.Getting Started Documentation +++++++++++++++++++++++++++++++ May19th 2017: +++++++++++++ CLOSED:AO will create proposal for how to improve Getting Started, and post to the mailing list. This is now here: https://drive.google.com/file/d/0B-n- iLEM1iXrTFdkRV82S0wweWM/view?usp=sharing. OPEN:AO will organise meeting to agree key concepts with wider team. CLOSED:TK, SY, AH will review Getting Started proposal at https://drive.google.com/file/d/0B-n-iLEM1iXrTFdkRV82S0wweWM/view?usp=sharing and post comments to mailing list CLOSED:NG will start to rework Getting started based on proposal. Post to mailing list when staging server is available May26th 2017: +++++++++++++ NONE: 2. Writing First Application Documentation ++++++++++++++++++++++++++++++++++++++++++ May19th 2017: +++++++++++++ COMPLETE:AO and JA will create proposal for Writing First application May26th 2017: +++++++++++++ OPEN: AO to update this proposal for Key tasks, SDK, Transaction ID explanation, and code snippets as reference material and other comments from above. OPEN: AO to create proposal for Writing You First Smart Contract Jun02nd 2017: +++++++++++++ OPEN: AO: Incorporate comments into final proposal OPEN: LW: Work with MP, NG, JA to help with design of documentation. OPEN: MP to create JIRA tickets for documentation work. 3. Overall Structure for TOC ++++++++++++++++++++++++++++ May19th 2017: +++++++++++++ OPEN: AO will create proposal for high level TOC restructure based on user types May26th 2017: +++++++++++++ CLOSED: Key personae proposal: https://drive.google.com/open?id=0B-n-iLEM1iXrOUdNdHpFaGp2NUU MA, J, AO propose renaming Noah to Bao, Blockchain Administrator JG will comment to mailing list MA will comment to mailing list OPEN: JG willing to help create/review proposal for high level TOC restructure OPEN: AO, JG and MA will create proposal for key Concepts in a Blockchain Jun02nd 2017: +++++++++++++ OPEN: MA will assist review of this material. OPEN: AO to incorporate feedback from this meeting into proposal. OPEN: MP to create JIRA tickets for documentation work. Jun09th 2017: +++++++++++++ OPEN: AO,JA to incorporate comments from review 4. Improved Process for Action Items ++++++++++++++++++++++++++++++++++++ May26th 2017: +++++++++++++ CLOSED: AO to create better mechanism for action items. Link to JIRA tickets. Jun02nd 2017: +++++++++++++ No new actions Best regards, Anthony. Unless stated otherwise above: IBM United Kingdom Limited - Registered in England and Wales with number 741598. Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU |
|
|