Handbook

[tangjeff0]

The Athens Research handbook is the central repository for how we run the Athens project. This github issue is a collection of tasks and the comments section can be used for general feedback and suggestions.

Links

• Handbook (gitbook)
• Handbook (github .md files)
• Handbook page in our public Roam database

Tasks

Priority Levels

• P1: high priority
• P2: medium priority
• P3: low priority

P1

• MVP contributing documentation.md (great reference https://learn.netdata.cloud/contribute/documentation) https://app.gitbook.com/@athensresearch/s/handbook/contributing-1/contributing-documentation
• MVP organizations scheme

P2

• migrate to gitbook
• migrate clojurefam docs/resources into handbook
• Centralize all documentation -> Migrate ClojureFam / School of Athens docs to here and archive ClojureFam
• Athens gold color hard to read on white background *changed to athens blue
• create an ARCHITECTURE.md create an ARCHITECTURE.md athens#765
• https://app.gitbook.com/@athensresearch/s/handbook/contributing-1/contributing-documentation make the contribution process for github more clear for those unfamiliar with github (more or less akin to Joel's description https://learn.netdata.cloud/contribute/documentation feel free to take this one Joel xD)
• link github section of contributing documentation to intro to github guide in our docs

P3

• adding pages (FAQs, Onboarding)
  • [ ]
• filling out empty pages
  • [ ]
• outdated pages that need updating
  • [ ]
• add logo, change brand colors
• figure out glossary.md https://gitbookio.gitbooks.io/documentation/content/format/glossary.html *glossary not possible
• add section like this: https://open-science-training-handbook.gitbook.io/book/#help-us-making-the-handbook-better

Notes

• alternative documentation tools to consider:
  • https://docusaurus.io/docs/
  • https://mdxjs.com/
• might want to update title of this issue to "Documentation" to encompass handbook as well as documentation within the code

[jsmorabito]

wondering if its possible to have multiple people edit the main issue description? have these links to add and i imagine more edits to come but dont want you, jeff, to have to manually come in and manually make the changes...i'll look into this

https://athensresearch.gitbook.io/handbook/
https://github.com/athensresearch/handbook

[tangjeff0]

@jsmorabito try now - you may be able to edit anyone's comments now.

I gave you "Write" access https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization

[joelhans]

I saw some discussion from @jsmorabito about the architecture of the handbook, and I'm wondering if there's been a consensus on it.

i'm looking at gitlab as a model (reading this https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/) and it seems like they have two separate entities: one is a handbook that outlines organizational processes/vision/higher level stuff and the other is the product specific documentation. I'm thinking it would make sense to do the same so for us we could have separate repo under athens research organization dedicated to the project handbook, then within athens repo can live its own collection of docs. and i think we can manage all of this through gitbook.

I'd advocate for this separation. It's more complex, but the end goal is getting users where they need to based on their problem/intent, the difference between wanting to know about Athens Research's culture vs. the shortcut to make a TODO.

I like the idea of two experiences:
1. The handbook, which is everything minus the School of Athens content as defined in Roam.
2. The School of Athens, which is user docs (using Athens + self-hosting, etc), developer docs, ClojureFam, and all the other goodness already outlined in that same doc.

[joelhans]

Anyways, if GitHub is meant to be a source of truth, then it seem important to document all the key user interactions in the handbook so that the information can be more carefully repurposed elsewhere, like on the Welcome page. I'll try to work up an outline of what I think would be helpful and tackles some low-hanging fruit, like a get started guide.

[seekanddefine]

I saw some discussion from @jsmorabito about the architecture of the handbook, and I'm wondering if there's been a consensus on it.

i'm looking at gitlab as a model (reading this https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/) and it seems like they have two separate entities: one is a handbook that outlines organizational processes/vision/higher level stuff and the other is the product specific documentation. I'm thinking it would make sense to do the same so for us we could have separate repo under athens research organization dedicated to the project handbook, then within athens repo can live its own collection of docs. and i think we can manage all of this through gitbook.

I'd advocate for this separation. It's more complex, but the end goal is getting users where they need to based on their problem/intent, the difference between wanting to know about Athens Research's culture vs. the shortcut to make a TODO.

I like the idea of two experiences:

1. The handbook, which is everything minus the School of Athens content as defined in Roam.
2. The School of Athens, which is user docs (using Athens + self-hosting, etc), developer docs, ClojureFam, and all the other goodness already outlined in that same doc.

Hi @joelhans, (Adding @jsmorabito since we were going to connect about the handbook today, not sure Matei's handle)

When I first read this, I agreed. After working on a proposed architecture yesterday (hasn't been merged yet), I have a few considerations:

We are building while living in the structure:
-needs to be a fully functional document
-needs to be accessible by everyone in the community
-needs to acquire a form that supports our culture of all-remote, asynchronous communication
-needs to be flexibly iterative, so that it can be easily improved

Typically I'm all about planning ahead, but in this case would it be better to have everything in one spot? How difficult is it to switch later and create a new cultural norm for all the users?
If we are hoping that users become contributors as an ideal case, then should we have everything that contributors and users need in the same spot?

Other handbook related thoughts:

1. Add a top navigation bar with: Website Github & Open Collective Links.
2. Add the Athens logo.
3. Add a glossary.md so that glossary words throughout the handbook can be defined with hover

As a newcomer here, I'm feeling a little frustrated with navigating the cloud of Athens information. Questions that come from that are:

Q. How can we make it as easy as possible for new people to contribute?

Q. How can we better track communication iterations as the team grows?

Since the number of one-to-one relationships grows with the square of the total people. For a 20 person team, that's 190 relationships.
Case. I've been working on Athens for a week. I've communicated with at least 20 different people about the handbook. Discussions happened in private discord chats, open discord channels, roam meeting notes, github discussions, github comments, drafts happened in my Athens and then were moved to Roam, changes were done in gitbook, the handbook itself connects with resources in Notion, miro, open collective, etc. I'm all about autonomy. I come from a hierarchical command and control culture where I had to ask permission and get approval before doing anything which made progress abysmally slow, but right now I'm feeling like I'm managing various relationships and interfaces in such a way that it is really slowing down the work getting done. Can the handbook make it easier to navigate growing pains?

Q. What expectations do we have about contributors reading the handbook and how are they communicated?

[joelhans]

@seekanddefine I agree with the frustration in navigating the cloud of information! The more I think about it, the more I agree that instead of continuing down a path of silos, the first goal should be put all the darn things in one place.

I peeped at the handbook structure in Roam and couldn't find anything related to user docs. I can share some ideas I have in a personal Athens DB if there isn't a plan already. I ask because of a certain PR ☝️.

[joelhans]

Hey @jsmorabito, happy to take on the doc on contributing to the documentation. I'll create an issue for it and do my best to label/categorize it—I'll have to see what permissions I have to do so.