search

architect / arc.codes

The Architect web site! 🌩
https://arc.codes
Apache License 2.0
315 stars 102 forks source link

Architect docs v3 master issue #193

Closed ryanblock closed 3 years ago

ryanblock commented 4 years ago

Hey all! We are passionate about providing folks with excellent documentation docs, and Architect's current docs have fallen short of that goal and standard. I'm asking for the Architect community's help in executing the largest overhaul of Architect's docs since the framework's creation.

I've outlined the stages of this project below, the proposed hierarchy of content, and a detailed content outline. Once we've resolved on the outline, I'll generate stub documents for everything below, and get a v3 branch going for everyone to begin contributing to.

Worth noting: the outline is just an outline; even once resolved, sections and entire documents may change and evolve, and some may be deemed unnecessary – there is absolutely room for such discussion!

A tacit goal should be that, once complete, all open content-related issues should be resolved (#116, #118, #123, #132, #141, #143, #144, #145, #147, #155, #167, #168, #169 are assigned to docs below).

I'd love to see this ship by the end of March. As you can see below, we have over 50 docs to (re)write – there's no way we can do this without you!

Project stages

Bold is current stage

  • [x] [2020-01-27 - 2020-01-28] Initial proposal
  • [x] [2020-01-28 - 2020-01-31] Feedback
  • [x] [2020-02-03 - 2020-02-07] Edits / amendments to doc outline
  • [ ] [2020-02-07 - 2020-03-25] → Creating + editing content
  • [ ] [2020-03-07 - 2020-03-21] Final signoff
  • [ ] [2020-03-26 - 2020-03-31] Publishing to production

Adminsitrative tasks (@ryanblock)

Content hierarchy

Note: a handful of docs may exist at the category level

Content outline

Guides

Get started

Guides

AWS

Reference

- [x] Architect project structure [fixes #144]

Overview Creating new resources & files Special files & folders

Architect manifest + config

Static assets

Functions

Database

- [ ] Domains

TBD (feature forthcoming)

- [ ] Macros

Overview Getting started Examples

CLI reference

@architect/functions runtime helper reference

About

grahamb commented 4 years ago

Something that would be helpful, and I know has been raised before, is a list of the bare minimum permissions required to execute an arc deploy. I would love to be able to create a role that can deploy via arc and not have to give it * permissions on everything.

ryanblock commented 4 years ago

@grahamb a legit request and understandable! However, I think there continues to be misinformation and misunderstandings around this topic.

Just to level set:

Therefore, if you create a minimum permissioned role for Architect that includes iam: *, even if that role has a limited set of permissions, you've likely still effectively just granted that role the ability to create new users and roles with AdministratorAccess.

In more practical terms, if complete isolation and maximal security are chief considerations of a deployment, the industry is coalescing around account level security as the best practice; thus the proper boundary for isolation should be at the AWS org account level, not at the IAM role level within an org account.

Hope that all makes sense, but if not please let me know! Also, I've added this topic as a section to the AWS credentials doc in the outline above. (Will likely use much of the above text in it, even.)

Thanks for raising this again, we need to ensure people understand this stuff!

Reference

leftieFriele commented 4 years ago

I think the outline looks very good and will be a big improvement 👍 . As a newcomer I felt the current outline did a decent job too, however it was in the details where I found the docs to be lacking in detail and in supplying good context in the beginning. When it came to details I found some of the sample GitHub repos that you @ryanblock and @brianleroux created to be very helpful. The docs do a good job of showing off arc's simplicity, but the docs never show a complete project with all the details in it. My points are perhaps more related to the work on the details 🙇

ryanblock commented 4 years ago

@leftieFriele yeah, the details are where things are truly lacking. My expectation for this process is that we will start with a stub of each new document and rewrite it from whole cloth.

Out of curiosity, what does a "complete project" mean to you in this context?

(Related, there are lots of example projects here, but we don't show them off: https://github.com/architect-examples/)

leftieFriele commented 4 years ago

@leftieFriele yeah, the details are where things are truly lacking. My expectation for this process is that we will start with a stub of each new document and rewrite it from whole cloth.

Out of curiosity, what does a "complete project" mean to you in this context?

(Related, there are lots of example projects here, but we don't show them off: @architect-examples)

I was not aware of @architect-exmaples, it is exactly what I was thinking of in regards to "complete projects" 👍 My apologies for not having picked up on that repo.

ryanblock commented 4 years ago

@leftieFriele in all candor, we haven’t done a good job of making sure people found it, not have we done a good job of keeping the examples in there up to date! There are many still on Arc 5 for example. We can definitely use help there.

Perhaps we should post and maintain a help wanted doc for contributors to easily find things we could use a hand with!

konsumer commented 4 years ago

@leftieFriele Agreed. I am working on a top-to-bottom example of using dynamob, mapped to this AWS example. It's my plan to use the data as a base for other examples. Like make one tuned to a specific set of access patterns, then show the same data in a GraphQL server (with very different access patterns,) for example. I am still finishing up the base-example, but should be done soon. I could use help applying similar best practices to other use-cases, and I think frontend examples would also be great, so you could say "this has a graphql server based on this, and a nextjs frontend". My goal is to make a few projects that show the actual usecases I have for arc (lambda frontend for dynamo data, modeled in a way that is efficient) but I could see the example being a good base for lots of other usecases.

ryanblock commented 4 years ago

Just an update, we're now in the Edits / amendments to doc outline phase – please suggest any final proposed outline edits and amendments!

juliedavila commented 4 years ago

I would like to see a userland directory as maybe a standalone page? Custom macros are installable via npm, it would be cool if folks to could share their stuff on arc's docs 🤷🏻‍♀️.

ryanblock commented 4 years ago

Yes! See also: https://github.com/architect/architect/issues/667

ryanblock commented 4 years ago

Alright, here we go! https://github.com/architect/arc.codes.next

I'd like to ask y'all to take on some docs to write!

How about for now please PR here with your name commended beside any docs you'll be writing a draft of: https://github.com/architect/v3-arc.codes/blob/master/src/docs/ToC.js

Guidelines:

Notes:

filmaj commented 4 years ago

Hey, wanted to help out with this. I sent a PR to the other arc.codes repo fixing some stuff but there's a new repo here now!

How should we go about dividing up the work? You mentioned sending a PR and commenting beside lines in the ToC.js. I don't see an open PR with this so kinda confused how this will work. One alternative suggestion: file issues for each section that needs writing, and assign these out to users? I want to help! Help me help you!

brianleroux commented 4 years ago

you know with everything going on we sorta let this fall off the radar but def need to revisit. heres a short list of things I think we should get going asap:

brianleroux commented 4 years ago

FYI started working my way thru this and will chip at this every day. I'm just starting w the content. @ryanblock would be cool to get your github-action-fu on the CI/CD side. I could bootstrap w Begin.com for now maybe?

brianleroux commented 4 years ago

well that was ridiculously easy https://shiny-hsd-staging.begin.app 🚀

filmaj commented 4 years ago

let me know how I can help out, I'm confused how best to divvy the work up.. i've been working a lot with static, http and functions (arc.http and arc.data) lately so that stuff is fresh. feel free to just assign stuff to me one at a time.

filmaj commented 4 years ago

to echo some of the existing comments in this thread, i think it would be beneficial to enshrine a tutorial in these docs, that is, building a deployable app from start to finish, showing off some common patterns that folks typically have to master to be able to get into a good arc development flow. this should, i think, include: data modeling, code sharing across functions and static asset handling.

i like the way the reactjs docs are structured (https://reactjs.org/docs/getting-started.html#learn-react): to reach the goal of 'learning react' (a tall task for anyone), they divide the approach up into "learn the concepts" and "learn by building". i think this approach would be beneficial for arc, too, with the 'concepts' section reusing lots of the existing content from the v5 and current v6 docs, and the 'building' portion going step-by-step through building a usable example app.

just my $0.02.

brianleroux commented 4 years ago

eh fil WDYT of https://learn.begin.com in this context ? its designed to walk a frontend developer through these basics to get them rolling / def could be improved and/or lifted to architect

filmaj commented 4 years ago

That's pretty amazing and relevant content. totally that kind of thing is what i was talking about. i had no idea that existed :D

brianleroux commented 4 years ago

yeah we can mirror / mimic it. the idea there is onboarding frontend developers with the major topics of interest to them in a sort of growth path. could see doing same with arc website and adding a few more paths: database/persistence centric learning, feedback control systems, deep integration with cloudformation using macros, etc

filmaj commented 4 years ago

yeah i think it's super relevant and would be helpful for newcomers. i think the challenge in this issue is that, as these kinds of adjustments (i.e. add a tutorial? a new 'concept' or 'principle' section added?) land, it takes some effort to filter it back into the overall learning picture (which @ryanblock helpfully laid out as the 'outline' in the original post). the kind of local / organic / fill-whatever-need-is-most-present sort of approach to the existing docs is how we've gotten into the situation where there is all this great content, but spread out all over the place (github.com/arc-examples, learn.begin.com, arc.codes).

docs content is hard! but i think we can do it well if we can keep the high-level / big picture / outline in mind and updated as we iterate on the micro content.

filmaj commented 4 years ago

Noting this down: we should describe how to reference an index, via IndexName: "{pk-field}-{sk-field}-index"

Another thought: should the docs be nudging people towards using multiple tables in Dynamo? Seems like that is against the best practices (dynamo's benefits seem to be realized best when you can use it in a single-table design). Currently the examples in the docs all seem to have one-table-per-entity, akin to relational database design. Though I struggle with this question as single table design is hard and probably not arc's domain / problem, though I also don't want to nudge people to use dynamo within arc in a matter that is antithetical to dynamo's design and performance constraints.

brianleroux commented 4 years ago

yeah its a good q. I think they can arrive there themselves … single table design is more of a goal state than edict. you can absolutely have low to medium traffic with a totally normalized schema and probably won't care at all. high bandwidth scenarios where you want to squeeze every possible performance advantage will invite evolution/refactoring to a (probably additive, ironically) single table. even then I'm not super convinced it would be a priority.

worth saying too, there always exceptions to the single table goal state. you probably do not want to store durable important data, like user accounts, in the same place as ephemeral scale-to-zero data like session tokens. backups, etc are totally different. if anything I'd counsel we document that we recommend people to build their app and use iterative discovery to arrive at ht optimal single table design…because it is extremely unlikely they can predict it (unless they're porting to a known domain and have confidence they are executing the pattern properly).

filmaj commented 4 years ago

Jumping back into this one!

So @ryanblock's overview / original post is gold. I would prod/question a few points in the overall structure - nits, mostly - but I think it's important to have agreement on that structure as we move forward on the work.

Suggestion 1: Tutorial + Walk Through Guide

I will reiterate a point I brought up earlier that I think what would help a lot of people is a 'beyond hello world' example app that shows off non-trivial functionality as well as pair it with a set of guides walking through how to build that up. This brings me to my first suggestion on Ryan's outline: replace the "beyond hello world" Group of Docs under the "Get Started" Category with a "Tutorial" Group that goes hand-in-hand with a de-facto arc example app. The "beyond hello world" Group in the original outline contains, what looks like to me, reference or guide documentation for each of the major arc primitives. I would recommend moving those Docs instead to relevant Reference and/or Guides Categories; I would prioritize writing up / having Reference Docs for each of the primitives, and optionally spill over any additional (but necessary) content into Guides Docs.

This begs the question: what should the tutorial and example app contain? My suggestions in terms of functionality to include (not exhaustive):

Suggestion 2: State project goal

Doesn't have to be too dramatic or involved, but this should be close to the initial content that new users see. This could totally be aspirational and not completely reflecting reality. Thinking out loud, but perhaps 'toolset to build apps serverlessly with any cloud provider', even though only AWS is implemented right now. Stating this goal is important to me as I think it puts the right lens on all further work. I personally am more motivated to work on a project if I can see what the goal is, where we're headed on the horizon, and helps me understand what to work on within the project as I can compare the cost/benefit of each project task against the project's vision to understand how to prioritize issues. This suggestion leans on my previous work at Adobe's open source office (I wrote up a set of docs on what and how open source projects should document to help lower the barrier to entry and encourage+retain contributors).

Once a project goal is clearly stated and has buy-in, then with a combination of that vision/mission statement + specific, tactical outstanding tasks, one could potentially assemble a rough roadmap and provide clarity to users + contributors on what is coming next in the project.

Questions

filmaj commented 4 years ago

Re: infra to run the site on, I was looking around at what the openJSF is able to provide and was able to find a draft of openJSF infrastructure services the foundation is thinking of / already is providing (was poking around openJSF "cross project council" repo github.com/openjs-foundation/cross-project-council). There is no mention of a shared AWS account (that would be the homerun!), but it does mention the following bits that maybe we should chase up

filmaj commented 4 years ago

Re: arc 6 in the docs, derp, already there; https://github.com/architect/arc.codes.next/ uses arc 6 in a simple static site setup, plus eleventy to generate the static assets.

I'm going to take a stab at one or a few PRs to the arc.codes.next repo with some of the ideas I covered in here. I will start with the 'stating project goal' tweak I mentioned above as I think that will need changing the ToC and the home page a little bit.

filmaj commented 4 years ago

I took a stab at tackling the "project goals" suggestion I mentioned above. I deployed my fork of arc.codes.next to begin (https://sweet-utn-staging.begin.app/), but only the homepage loads - all other links/pages seem to load the homepage.

You can still see the compare-view of the branch I have for this here: https://github.com/architect/arc.codes.next/compare/master...filmaj:mission-vision. I tried to remove references to AWS and keep it cloud agnostic, at least on the home page and the mission/vision statement page, as I would like for architect to aspire to (eventually) support different cloud providers.

Perhaps this particular topic and conversation belongs in its own issue thread somewhere?

I'd also love to hear feedback on the walkthrough + tutorial app combo suggestion I made earlier. I am thinking we should add a dedicated Group called "Tutorial" (singular) under the "Guides" Category that would contain the sequential, building-on-themselves series of mini-guides slowly building up the 'official' example app (that I roughly sketched out in a previous comment). The existing "Tutorials" Category would be renamed to something else (perhaps "Deep Dives" or "How Tos").

P.S. the arc.codes.next repo is in pretty good shape, was easy to get going on it!

brianleroux commented 4 years ago

eh Fil sorry been meaning to respond in detail but a quick tip! by default we enable ARC_STATIC_SPA=true for static apps (which always redirects to the home page). this default was probably a mistake…I kinda regret it…but anyhow setting ARC_STATIC_SPA=false will revert the proxy to behavior you and I would expect

filmaj commented 4 years ago

Works as expected now, thank you 😄

filmaj commented 4 years ago

Thought more about 'where to host' the docs and on second thought, if Begin would be gracious enough to host them, then I see no problem with that. On the other hand, if the OpenJSF does have an AWS account they are willing to spot the project, then that would be ideal as it allows the project to eat its own cooking.

brianleroux commented 4 years ago

we have one! we have to get you creds =) its a bit faster to prototype with begin.com rn but we'll move it to openjsf infra for sure

tbeseda commented 3 years ago

A lot of work got done here and is still great reference for me! Closing since this is a bit dated and superseded by #411