Giter Site home page Giter Site logo

handbook's People

Contributors

agentydragon avatar arkredm avatar joelhans avatar jsmorabito avatar sawhney17 avatar seekanddefine avatar ssjoleary avatar tangjeff0 avatar

Stargazers

avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar

Forkers

jsmorabito arkredm seekanddefine joelhans sawhney17 agentydragon phrohdoh ssjoleary

handbook's Issues

Long-term handbook vision

The handbook is an open, living set of documents that detail the people and processes behind the Athens community. That includes how the Athens application works, how the community can create content and self-organize, and how Athens Research operates as a company. Because we want to build in public, work transparently, and learn as a community along the way, a huge part of the success of Athens is tied up in the success of this handbook.

The handbook has two goals: 1) be the source of truth for the Athens ecosystem, and 2) help users be extremely successful at using Athens.

We're mostly focused on the first goal now. We have to understand exactly what we want to put into the handbook, scope out that work in granular tasks, and then push forward in creating content. I imagine we'll be working on this source of truth goal for another 3-4 months (September-October 2021), especially around anything related to the operations of Athens Research itself. The company is astoundingly new, and we have a ton that we still need to figure out. Product-wise, once we've established the fundamentals, most additional tasks should be related to organizational tweaks, small improvements to existing docs, or documenting new features, and that will be an ongoing process until the end of time.

Next, we'll focus on success. This will be much more exciting, as we'll break out of the product space and into how people use Athens. The type of content changes. It'll be more tutorial-like in nature, showcasing different types of workflows, and information on how to solve very specific types of problems that users might be facing, such as when to use pages vs. blocks, how to use Athens as a researcher, or the difference between taking notes on multiple daily notes versus condensing everything into the same topic page. I also imagine assets like a template gallery being part of this, and maybe some pre-configured graphs with specific workflows already implemented so that new users can just download them and hit the ground running.

It'll take a long time to achieve these goals, and since they're moving targets, we'll always have to optimize and tweak to get things just right.

new: Write a Get involved/Request new features doc

Published file: https://athensresearch.gitbook.io/handbook/community/get-involved/learning-at-athens-academy-education/request-new-features
Markdown file: https://github.com/athensresearch/handbook/blob/main/community/get-involved/learning-at-athens-academy-education/request-new-features.md

This is a really important page for the Athens community, as we have lots of feature requests, and we want to make sure they're managed thoughtfully through the entire process.

This document should answer the following questions:

  • How can I put my support behind an existing request?
    • Find the request on GitHub and give it an vote.
  • What are some prerequsites to filing a feature request?
    • Search Github Issues and Github Discussions to see if your feature has already been requested
  • Where do feature requests go?
  • What is a good feature request?
  • What are the next steps?
    • A few possible outcomes:
      • The core team puts it on the roadmap and starts working on it.
      • An external contributor starts working on it.
      • The core team creates a Gitcoin bounty on it to prioritize and incentivize the work.
      • Nothing. Sometimes we can't support feature requests, for example, if they conflict with our vision.

new: Write an advanced Athens usage doc

https://athensresearch.gitbook.io/handbook/community/athens-guide/advanced-usage
https://github.com/athensresearch/handbook/blob/main/community/athens-guide/advanced-usage.md

The existing page offers some ideas of what the content on this page might be. For now we can focus on adding a few of these use cases onto a single page, then eventually break them up into separate pages when there's 3+.

  • Build a Zettelkasten
  • Organize annotations from articles and books
  • Journaling
  • Creating a newsletter with blocks
  • How to use a pipeline system
  • Organize scattered ideas
  • Templates

correct "daily notes" shortcut

per https://github.com/athensresearch/athens/blob/47efb818a02a3e74e6e994337b0e1eb30c83199f/src/cljs/athens/listeners.cljs#L111 the shortcut is <alt + d> but the handbook's current "daily notes" page says <ctrl/cmd + d> (which is at odds with the actual code and the current "keyboard shortcuts" page

The "daily notes" page should be updated to either say alt+d or just reference the "keyboard shortcuts" page so we don't have duplication which opens the door to out-of-date information such as this.

Alternative documentation platforms

🚧 WIP 🚧

We're looking into migrating away from GitBook as the deployment platform for the Athens Research handbook. The timeline is still rough, and probably won't begin until the handbook reaches an MVP state.

This issue is meant to create discussion around the pros/cons of alternative docs platforms, and the migration as a whole. Would love some feedback or thoughts on platforms that folks might have tried!

Pros

  • Establish a "docs-as-code" workflow to ensure that this repository and the deployed handbook are always in sync
  • Enable more customization (styling and functionality)

Cons

  • Lose visual editing capabilities, which makes certain types of contributions much easier than Git+GitHub
  • Lose specific GitBook features
    • Export to PDF
    • Automatic table of contents for pages that nest other pages

Alternatives

Docusaurus

Docz

  • https://www.docz.site/
  • https://github.com/pedronauck/docz
  • Gatsby-based
    • I personally haven't had great experiences with Gatsby, but maybe Docz is abstracted enough that there isn't much dealing with GraphQL
    • Works with many existing GatsbyJS plugins, which is a plus
  • Uses Gatsby's component shadowing to customize the look & feel
  • Supports MDX to embed interactive React components

resolve duplicates in handbook

Maybe Gitbook creates some duplicates and gets out of sync, but noticing duplicates in the source files for this repo.

One example. Two directories with similar functions. onboarding-for-new-clojurians.md shows up 4 times.

school-of-athens
├── clojurefam
│   ├── clojurefam-cohort-and-team-rosters.md
│   ├── learner-commits.md
│   ├── onboarding-for-new-clojurians.md    # 1
│   └── README.md
├── clojurefam.md
├── github-guide.md
├── school-of-athens-faq.md
└── school-of-athens.md

learning-at-athens-academy-education
├── clojure
│   ├── clojurefam
│   │   ├── clojurefam-cohort-and-team-rosters.md
│   │   ├── learner-commits.md
│   │   └── README.md
│   ├── onboarding-for-new-clojurians.md    # 2
│   └── README.md
├── clojurefam
│   ├── clojurefam-cohort-and-team-rosters.md
│   ├── learner-commits.md
│   ├── onboarding-for-new-clojurians.md    # 3
│   └── README.md
├── knowledge-management.md
├── notetaking.md
├── onboarding-for-new-clojurians.md         # 4
├── README.md
└── research.md

enhance: Edit and organize the community guide Overview

https://athensresearch.gitbook.io/handbook/community/get-involved/contributing

https://github.com/athensresearch/handbook/blob/main/community/get-involved/README.md

This document should act as a portal for different ways community members can contribute to Athens and its ecosystem. The pages under Get Involved serve as a general structure, but there needs to be some cohesion around the purpose of contributing and some pathways for different "types" of contributors.

new: Write a Get involved/Review & submit pull requests

Published file: https://athensresearch.gitbook.io/handbook/community/get-involved/learning-at-athens-academy-education/review-and-submit-pull-requests
Markdown file: https://github.com/athensresearch/handbook/blob/main/community/get-involved/learning-at-athens-academy-education/review-and-submit-pull-requests.md

Should probably be re-titled Submit & review pull requests, as submission is typically the first step to becoming a contributor with enough privileges to review PRs from others.

More information coming soon.

Handbook

  • branches

  • main

  • drafts

  • organizing pages into groups

  • adding pages (FAQs, Onboarding)

  • filling out empty pages

  • editing existing content

  • style guide?

  • are our values coming out?

  • are we linking to the resources we want (e.g. ClojureFam)?

Emphasize the Vision Page

The vision page is one of the most compelling parts of the whole documentation. It's what got me excited about the Athens community, and was one of my entry points into the PKM space as a whole.

If it were placed either right before or after the Code of Conduct in the TOC, then new readers would be able to discover it and see that Athens isn't just a Roam copy, but that it has a clear purpose for what it wants to achieve, and an overarching plan for getting there.

In any case, it should be recognized as a tool for onboarding people into the PKM space.

new: Add a Features/Backups doc

We have a lot of questions about how Athens uses backups (the .bkp files).

The underlying philosophy:

  • We believe in zero data loss above all else.
  • We let user manage their own data.

Questions to answer:

  • How and when does Athens back up my data?
  • Where does Athens store the backup files?
  • Can I delete old backup files?
  • What is the process of restoring from a backup?

Some context and information that should help answer these questions:

Each backup looks like {TIMESTAMP}-index.transit.bkp . This means the user's db folder will eventually have many backups. This is obviously not space-efficient, and expects users to delete/manage their old backups, but this effectively removes any possibility of data loss. We will eventually come up with other approaches for writing and redundancy that are more performant and space-efficient, but the first principle should be no user data loss, which we've accomplished with this solution.

Note potential issues with stylefy cache

The way we're handling style caching with stylefy (not clearing the cache during development), occasionally the styles in localStorage will get corrupted and to solve it you have to clear the stylefy cached styles.

This issue, for as long as it remains an issue, should be noted in the handbook.

enhance: Add more information to the Get Involved/Improve Design doc

https://athensresearch.gitbook.io/handbook/community/get-involved/learning-at-athens-academy-education/contributing-design

https://github.com/athensresearch/handbook/blob/main/community/get-involved/learning-at-athens-academy-education/contributing-design.md

This document feels sparse and unwelcoming. We should have some more specific ways to get involved, a suggestion to reach out to @shanberg on Discord, and maybe a few specific areas where a contributor could most easily help with design.

Pinging @shanberg for any guidance/feedback.

Sync license files

After doing the work in #33, I noticed that the LICENSE file in the root directory and the license page at /about/untitled.md are not the same.

I'm guessing it's the LICENSE file that's outdated, and we want to use the EPL license, but I want to get confirmation before I change anything.

@tangjeff0 @jsmorabito

enhance: Edit the Get Involved/Contribute Documentation doc

https://athensresearch.gitbook.io/handbook/community/get-involved/learning-at-athens-academy-education/contributing-documentation

https://github.com/athensresearch/handbook/blob/main/community/get-involved/learning-at-athens-academy-education/contributing-documentation.md

Self-assigning this TODO, as I wrote the document in the first place.

Enhancements include:

  • Update the list of folders and what they do
  • Update the GitBook section with new information
  • Add some quickstart items
  • Update link from Documentation project -> Handbook project

Handbook

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

Tasks

Priority Levels

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

P1

P2

P3

Notes

new: Write a Get Involved/Submit Sample Templates or Databases doc

https://athensresearch.gitbook.io/handbook/community/get-involved/learning-at-athens-academy-education/submit-templates-or-databases

https://github.com/athensresearch/handbook/blob/main/community/get-involved/learning-at-athens-academy-education/submit-templates-or-databases.md

This should explain what a sample template might look like, and should include a reference to Google Drive folder where one can leave a sample index.transit file: https://drive.google.com/drive/folders/1E8z-s33PfzNCGxEsZNQlB5niVq9bKQg0?usp=sharing

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.