Documentation structure

[atoav]

Before investing a lot of time, I thought it would be better to outline a plan for the documentation. The stuff that is there is in parts not too bad, but it lacks a clear structure. This is IMO quite important, because the useres should feel that everything e.g. the Schematic Editor can do is listed in the section Schematic Editor.

I suggest we divide it into these 6 main sections:

1. About

This is the landing page, describes what horizon EDA is, what it is not and links to all the important pages. This is mostly about giving the users honest information so they can decide whether it is something for them or not, so a Feature overview.

2. Getting Started

This is a Quick guide how to get started with the software: Download, Setup, Downloading the official Pool (if necessary), Starting a Project, fundamental interface information (like the spacebar menu and the interactive manipulator). All of this should be kept on a basic level and it should be a quick read, while it could highlight some nice features (those who are interested after reading the About section should feel what is behind the whole thing).

3. Schematic Editor

A more detailed documentation of the schematic editor
Additionally things like:

4. Board Editor

A more detailed documentation of the Board editor
Additionally things like: How to import dxf, exporting step, fabrication output, Copying Layout and Placement, .

5. Pool Manager

A clear definition of the pool and its merits and how thinks work together, including info about parameter programs, padstacks and the like. A "guide" on how to create a package and a part. Link to resources and information for contributers. Suggestions how to organize pools.

6. Advanced Topics

Anything that doesn't really fit in

• Building from Source
• CLI usage
• Maintaining pools with git
• Generating Parts by scripts
• ...

---

All of this probably demands a different layout for the menu, probably something like this:

I have no idea how to change this on my own, but with a little help I could fill the skeleton up with content and copy existing things over. Maybe making a branch would be a good idea?

[atoav]

It could make sense to add a "Basic Interface" Section before the Schematic Editor, where common actions (Grids, Interactive manipulator, selection, etc could be explained), what do you think?

[atoav]

Okay I tried to create a more or less complete outline of what the whole structure could potentially look like (feel free to expand):

About

• Introduction and Quick Links
• Feature Overview
• Why horizon EDA?
• TOC

Getting Started

• Installation
  • Linux
  • Windows
• Setting up a pool
• Creating a new project
• Drawing a Schematic
  Show how to draw a simple schematic, while highlighting some interface features like spacebar menu and the interactive manipulator, etc
• Creating a board
  Create a simple board and export it

Basic Interface Usage

• Spacebar Menu
• Drawing
• Selection
• Moving (Interactive Manipulator)

Schematic Editor

• Basic Concepts
• Drawing
• Sheets
• Schematic Properties
• Annotation
• Buses
• Net Classes
• Power Nets
• PDF Export
• BOM Export

Board Editor

• Basic Concepts
• Rules
• Layers
• Placing Parts
  (Includes the whole back and forth between schematic editor)
• Route Tracks
  (Includes differential pairs, vias, locking, moving, length tuning, backannotation, ...)
• Planes
• Grouping and Tagging
• Fabrication Output
• DXF Import
• 3D Preview and Step Export

Pool Manager

• Why a Pool
  • Units
  • Symbols
  • Entities
  • Packages
  • Padstacks
  • Parts
• Tutorial: How to create a package
• Tutorial: How to create a part
• Inherit from other parts
• Contributing to horizon's pool
• On pool organization
• Project Pool Caches

Advanced Topics

• CLI usage
• Color Schemes
• Building from Source
• Maintaining pools with git
• Generating Parts by scripts

[carrotIndustries]

LGTM, I rolled out your TOC suggestions in the wip branch. Rendered docs are at https://horizon-eda.readthedocs.io/en/wip/index.html

[atoav]

Okay, that was fast, I will check if I can start on it later this evening.

[atoav]

I remade the pool diagram you did over at horizon/docs to give it a little more clarity. I tried to mostly orient myself on your thing, but decided to leave a few things out (I planed to make a seperate thing that shows e.g. a single NAND entity using the same Unit etc.).

Does this look alright to you?

[carrotIndustries]

Does this look alright to you?

Awesome, looks much more clear than my drawing.

The Symbol box inside the "Single Power" unit box should be outside of the pin box as in the "single ended nand" unit box. Technically, the top/bottom copper layers in padstacks, aren't drawn as polygons, but shapes instead. Not sure if that's to detailed for an overview drawing.

[atoav]

Updated : )

[niclashoyer]

This looks really great! I just started looking into horizon and this solved a lot of headache.

[atoav]

@niclashoyer The thing that is not pictured here tho is, that other entities (e.g. a imaginary "Dual NAND") could use the same "Single Ended NAND" Unit. That way if we change something in the Unit or the Symbol, it changes for all parts using NAND Units at once.

Ah and in case you overlooked it here is the work-in-progress documentation which I am working on at the moment