atom/flight-manual.atom.io

Add better explanation of visual elements -- Pane,Panel,Dock,WorkspaceItems

Opened this issue · 0 comments

Summary

I am planning to create a PR for this myself but thought I would create a feature request first to see to give people a chance to comment.

I think that the flight manual would benefit from a new page "Atom Visual Elements" which would explain in one place, the layout in Atom, listing the visual element types, how they behave and how they relate to one another. I would take care to link to existing pages instead of repeating that content.

I imagine including these elements in the page:

  • image(s) showing the location of the panel areas and docks in relation to WorkspaceCenter.
  • description of how all (most?) views that you see are either WorkspaceItems or panels and the differences between them.
  • the strong relation between 'tabs' and workspace items but how some people do not use tabs so that's why they are not always referred to as tabs.
  • Workspace Item Containers -- WorkspaceCenter, LeftDock, RightDock, BottomDock.
  • Panel relation to the workspaceItem containers
  • What determines/limits where you can place WorkspaceItems

Motivation

When I started using Atom a year or two ago, the visual layout seemed pretty intuitive, but the flight manual and README.md in packages used the terms Pane,Panel,Dock,Tab,WorkspaceCenter, and WorkspaceItems, Workspace in ways that confused me and I could not reconcile with what I was seeing in Atom. When I started writing packages the API was hard to follow because a few basic concepts were unknown to me.

I have now been writing packages for a while and after learning the API and reading a lot of code I have a pretty good idea of the structure of the various elements and their intent.

It was a tough learning curve that I think that I could help others avoid.