search

AntelopeIO / Coalition

0 stars 0 forks source link

Documentation Antelope Workgroup #13

Open ABurton22 opened 1 year ago

ABurton22 commented 1 year ago

Will be around a month before ENF DevRel team can address

Kersten to verify who will take lead of the workgroup going forward.

Initial meeting scheduled for week of 5-9 September

Overall discussion about future documentation efforts of Antelope and coalition chains.

Work Group to be created to work on a solution:

Ted Jesse Aaron Guillaume (or representative) Yves further members to be discussed in Telegram Group

Which approach should be taken for Antelope? How to handle 3d party developments funded by the coalition that are required by developers, example Wallet SDKs? Central hosting by whom? Greymass, each Chain, Antelope?

That’s Aarons goal, too - both for the developer experience in learning this technology, as well as for search engine purposes and the discoverability of this content.

Possible solutions:

"Link-Tree" Page on Antelope page Central documentation on Antelope page (scraper based) Only chain specific documentation (manual or scraper based) Combination of both

Key argument of Ted (ENF) is differentiation of chains in marketing and developer outreach.

Telos argues that central documentation can be a key asset and strength of Antelope going forward.

Benchmark research for other chains proposed by Douglas to understand how competitive chains.

Various documentation pages available being maintained by each chain

A central documentation site for Antelope would be redundant, but page could be created and include links to chain resources. Proposal TED / ENF. EOS Team for documentation / developer relations currently 4 people.

Open source tool available to extract documentation from existing repositories, allows to build own documentation for all chains.

EOS will continue to manage and make comprehensive documentation available for its own community and thus also for other chains. This activity is funded by ENF.

https://github.com/eosnetworkfoundation/devdocs

https://github.com/eosnetworkfoundation/eos-system-contracts#readme

developers.eos.io is often linked by Telos for documentation purpose. Work for chains would be redundant to create all needed information. Links to EOS might not be optimal in new Antelope constellation.

Telos will evaluate the documentation generator for possible use.

aaroncox commented 1 year ago

I'm going to chime in here with my opinion, which I've shared in depth both on various coalition calls as well as in the Antelope Documentation Strategy telegram channel. The telegram messages begin here:

https://t.me/antelopedocstrategy/5

We need a comprehensive strategy for documentation that identifies different types of professionals seeking information about Antelope blockchains, and to use that information to tailor the user experience based on the readers interest.

The reason I am once again raising this as a topic of discussion is because all attempts to date have focused on a high level overview of the technology, rather than materials that are accessible and tailored for specific audiences. This includes the first efforts started by Block One and leads all the way up to the most recent efforts by the ENF.

Each time documentation strategies are created, it seems as if the content is geared towards singular developers capable of understanding and performing tasks across the entire stack (e.g. the mythical "Unicorn Developer"). The strategy around documentation is to walk these people from infrastructure setup, to API references, to contract development, and finally into basic client development. In reality, this is the 1% of our potential audience - and catering to this audience often complicates the experience for the 99% of others.

While we should absolutely seek to engage these jack-of-all-trades professionals to engage on all aspects of the Antelope technology stack, the reality is that adoption won't be driven by individuals. Adoption will be driven by teams where these sorts of responsibilities are divided and handled by those who are most proficient in their respective areas.

A documentation strategy tailored specifically for these different types of professionals to allow them quick and easy access to the information they need will enable organizations to be more successful building their products - and thus the networks they deploy on.

With that in mind, documentation should be broken into digestible chunks based on the readers interest. These sorts of specific readers includes, but is not limited to:

Optionally, each of these topics of documentation should also be branded in order to create an identity about that part of the tech stack and its purpose. The rebranding of the platform portion of the code to Leap was a great move in this regard and the Web SDK project will have it's own independent branding.

All of the above topics in reality should have independent documentation, perhaps even their own websites, each with the content related to other subjects interlinking where appropriate. No where in the above list should this documentation be replicated on a per-network basis, but instead simply provide links to the common documentation they all share.

This is a shared strategy for all Antelope-based networks to collaborate, share, and improve a singular experience for the professionals participating and utilizing this technology stack. It's a more difficult path than simply creating one giant cluster of information, but the extra effort put into designing the documentation strategy and documentation itself will reduce the effort the reader will need to expend while learning about this technology.

As an aside and to support the above thoughts on overall strategy, the Web Client SDK project will already use the above documentation strategy. The Web Client SDK proposal included the creation of an SDK-specific brand, website, and documentation to serve as the primary source of education for those seeking to build web-based applications.

When a web developer asks "How do I integrate my web app with Antelope?" or "How do I interact with Antelope using Javascript?" - the SDK website (something.com) will always be the first thing mentioned as the answer. This will be regardless of which Antelope-based blockchain they are looking to build on. It's something simple that can be clicked or typed in the browser, markets benefits to that developer about what its purpose is, and gives the potential adopter a straight forward path to dive deeper.

The end goal for Antelope documentation in total should be to replicate this same experience for each audience that is seeking information... regardless of if it is a systems administrators looking to deploy software, an app developer working on iOS/Android, a game developer, or even academics/developers looking to dive deeper into the protocols that power everything.