Refactor the Documentation

[Archmonger]

Current the docs are structured in a way that's difficult to digest, especially for IDOM beginners. Almost every page is overloaded with far too much information.

Pages within the Getting Started group needs to be as barebones on info as possible. You should think of this as a mix up between TLDR and ELI5. If you overload a new developer with too much information they'll immediately run away thinking this framework is too convoluted.

Most suggestions in here are reordering of things, but there's also a handful of new sections.

I may toy around with the ordering of sections, but I've been working on this for too long and wanted to post a draft before it hits 4am 😆 .

Side note: I still think the current theme really amplifies how hard it is to digest this info. Also, this refactoring may make the current theme's sidebar unwieldy as a consequence of making pages more readable.

---

Getting Started

• Install Guide
  • Flask, Sanic, FastAPI, and Tornado
    • Installing through pip
  • Django
    • Installing through pip
    • See configuration at django-idom
• Run Guide
  • Flask, Sanic, FastAPI, and Tornado
    • Using the Default Layout Server
    • Custom Configuration
  • Django
    • See details on django-idom
• Basic Concepts
  • Python Components
    • What are Python components?
    • Read More (Advanced)
  • User Event Handling
    • What is an Event Handler?
      • Why Use Event Handlers?
    • Basic Event Handler
    • Read More (Advanced)
  • Hooks (Automated Events)
    • What is a Hook?
      • Why Use Hooks?
    • Basic Hook
    • Read More (Advanced)
• Example Code Snippets
  • Note: If an example code snippet uses an "Advanced Topic", link to the relevant resources in the advanced topics section.
  • Hello World
  • Click Counter
  • To Do List
  • Slideshow
  • Material UI Slider
  • Advanced: Street Maps with Pinned Locations
  • Advanced: Trendline Dashboard
  • Advanced: Snake Game
  • Advanced: Mathematical X-Y Plot
• Your First Project
  • Note: Use this section to show that IDOM can do more than the silly demo components above, and can actually be used to create something akin to react.
  • Creating a Login Screen
  • Homescreen (Navbar and Viewport)
    • Note: Viewport will contain hello world at this stage
  • Creating Tabs
    • Note: Maybe one tab can be something similar to the matplotlib example except is a randomly generated (random data via life cycle updates) data graph, and another tab contains an image gallery?
  • Getting Ready to Deploy
    • See the Deployment Checklist

Advanced Topics

• Event Handlers
  • Note: Have a text blob that says see basic info at #/url-goes-here
  • Preventing Default Event Actions
  • Stop Event Propogation
  • Event Data Serialization
  • Differences With React Events
• Hooks
  • Note: Have a text blob that says see basic info at #/url-goes-here
  • Rules of Hooks
    • Only call outside flow controls
    • Only call in IDOM functions
    • Flake8 Plugin
  • Types of Hooks
    • Use State
    • Use Effect
    • Use Reducer
    • Use Callback
    • Use Memo
    • Use Ref
• Python Components
  • Note: Have a text blob that says see basic info at #/url-goes-here
  • Pure Components
  • Stateful Components
• Python Component Layouts
  • What is a Component Layout?
  • Layout Server
  • Layout Dispacher
• Javascript Components
  • Dynamically Loaded Components
  • Dynamically Loaded React Components
  • Custom Javascript Components
  • Distributing Javascript Components
  • Example: Simple Graph
    • Note: This is the example formerly in "Examples"
• Deployment Checklist
  • Disable Debug Features (?)
  • Load Components Non-Dynamically
  • etc. Not sure what else belongs here.

API

• Configuration Options
  • Normal Configuration
  • Debug Configuration
• Component
• Dispatchers
• Hooks
• Core Interfaces
• VDOM Constructors
• Standard HTML Elements
  • External sources
  • Content Sectioning
  • Text Content
  • Inline Text Semantics
  • Image and video
  • Table Content
  • Forms
  • Interactive Elements
• Logging
• FastAPI Servers
• Flask Servers
• Server Prefabs
• Sanic Servers
• Tornado Servers
• Test Tooling
• General Utilities
• Web Modules
• Widgets
• Misc Modules

Design Decisions

• Why We're Here
• Communication Scheme
• VDOM
• Ecosystem Independence
• Declarative Components
• Javascript Integration

Contributing

• Code Changes
  • Creating a Fork
  • Editing the Code
  • Development Environment
    • Running the Tests
    • Running Python Tests
  • Running Javascript Tests
  • Code Quality Checks
  • Make a Pull Request
• Documentation
  • Editing the Documentation
  • Adding a New Page
  • Building the Documentation
  • Make a Pull Request

Resources

• FAQ
• Changelog
• Roadmap
• Source Code
• Community
• Issues

[rmorshea]

This is exactly the sort of wholesale rethink of doc organization I haven't had time for. I think to move forward with this, we should create a google doc to more collaboratively reconsider the layout of the docs. Once that's done we can draft a change proposal.

As for the theme, we should probably stick with it for now but, we also shouldn't shy from customizing it where needed. For comparison, here's a gallery of other themes - I haven't really found any that I like any better than Furo.

[Archmonger]

I've created a Google doc and invited you as a collaborator.

Do you want to schedule a call to discuss the larger details?

[mx781]

Maybe not the best place to post this, but in favour of a new ticket...

As a quick fix prior to a full doc revamp, it might be worth adding the server port to the logs (or updating docs to reflect the default server port) - took me a while to find that idom.run() started a server on 8000 and not 8765 which is mentioned in the docs in places.

[Archmonger]

Agreed. I'll also follow the refactored docs step-by-step to ensure there isn't any other tidbits missing like that.

[rmorshea]

Just found this awesome resource which seems like a great way to think about organizing documentation.

[rmorshea]

It looks like React is planning to release a new version of their documentation that takes a "Hooks-first" approach to teaching React: reactjs/react.dev#3308

I have two thoughts on this:

1. I think we should wait to rework IDOM's docs until React has released theirs because 90% of their documentation should apply 1:1 to IDOM and it would be nice to piggyback on work that will clearly be given much more thought than I'll be able to on my own.
2. While there's been some discussion of introducing class-based components to IDOM, this change to React's docs is a strong indicator that they believe class-based components are a net negative for developers relative to hook-based components.

[rmorshea]

An alternative resource we could follow is Preact, but I suspect that it would still be worth waiting to see what the React team come out with.

[Archmonger]

My thoughts are that imitating JavaScript and React styling within Python isn't a great idea.

Developers using IDOM are python devs, not JavaScript devs. If things can be done cleaner in a pythonic & PEP8 way, I'd argue that's the right direction.

Or at least provide developers the ability to choose between PEP8/React styling methods.

But all of these opinions are contingent on there being no major technical limitations to CBCs (class based components). Especially in regards to hooks.