[Draft] AssemblyPress Integration Docs

Proposals
,
1

TL;DR

Create technical documentation to support AssemblyPress protocol integrations.

Introduction

This proposal stems from discussions around the use of Neume to index the onchain activity of the AssemblyPress protocol. Knowledge that would be collected during the initial stages of the integration can instead be captured here. This furthers the education goals of PA and sets the stage for the Neume integration through documentation.

This is intended to be a relatively small proposal, so the team may consist of just myself (@neatonk). That said, I think it would be beneficial to expand the scope a bit and include someone with an education focus that can help to shape this prop and fit the new docs into existing documentation efforts (cc/ @valcoholics and @estmcmxci).

Ask Details

The adoption of this proposal will result in documentation of the AssemblyPress protocol for the purpose of future integration and education efforts. This documentation consists of three parts:

  1. Additional NatSpec comments in the AssemblyPress code. This is largely done, but additional context, detail, and clarification should be added to better support integrations.
  2. HTML API docs generated from the NatSpec comments using the forge doc cli command. TODO: find a good example of forge doc output.
  3. An HTML page providing a high-level overview of AssemblyPress (based on this walkthrough) that anyone can use to grok the how, what, and why in a short period of time. This also serves as an entry point for integrators with links to the API docs and source code.

It is currently TBD how this documentation should be exposed.

Benefits

  • Support future integrations, e.g. with Neume for indexing.
  • Further the education goals of PA through AssemblyPress documentation.
  • Capture and share knowledge that would otherwise be lost without documentation.

Timeline

TBD

Budget

TBD

3 Likes
2

cc/ @salief @0xTranqui @thekidnamedkd

3 Likes
3

There have been 1-to-1 talks on wiping the docs.public---assembly.com site to a new updated and unified repo based on how the nextra site that was done for flexible sprint looks

ex. Managing Access Roles - Flexible Documentation

are you guys in alignment with that or is it useful to keep documentation for different PA products seperate?

1 Like
4

Flexi docs looking very fresh and Nextra is pretty nice tbh.

3 Likes
5

i personally think from an organizational/context sharing standpoint it would be rlly great if we could have all of our “official” (nothing is “official” which is the problem – and the good thing) docs live in one place, and if nextra is seeming like the best way to achieve that im all for it. had a easy time submitting a pr to the nextra based docs recently

2 Likes
6

this is really great @neatonk! one thing i want to call out is AP may be going thru some architetural changes over the next 2-3 weeks (or however long it takes us to get thru everything on the RFC + whatever else comes up), so may be best served starting this at the tail end of that, or if getting going sooner is helpful than expectations should just be there that things could change during the documentation build out process. ofc would want any changes to natspec to occur before/during the updates, rather than after we wrap up the RFC if possible

enshrining more legit docs for AP and prepping for the Neume build feel like high priority things for us, so im all bout this !

2 Likes