IA and Structure

[oubiwann]

Tasks:

• Identify core site areas to highlight on simplified landing page
• Decide upon top-nav menu items
• Decide upon bottom-nav menu items
• Identify major documentation categories
• For each major category, identify subcategories
• Identify which categories have content that should be versioned

Our information architecture is basically non-existent. We need to create one.

Part of Milestone v3 #62

[oubiwann]

The areas of the docs site we will need to better define (or create) include:

Learning LFE

• Quick starts
• An official LFE tutorial
• A link to "Learn X in Y Minutes"
• comparison chart (to another language)
• Casting SPELs with LFE
• SICP, the LFE Edition

Language Reference

• reference guide (short)
• user guide (long)
• cheatsheet(s)
• Style Guide
• Best practices for LFE programmers
• maybe link to the "official" LFE tutorial here, too

Tooling

• IDE setup instructions (Emacs, Vim, Sublime Text)
• Creating projects
• Compiling
• TDD

Useful Community Libraries

e.g., lutils, ltest, ljson, etc.

Building Applications with LFE

• tutorials by topic (OTP, RDBMS, web apps, NoSQL, messaging)

Contributing

• To LFE proper
• Creating new libraries
• To the documentation site
• Style Guide (again)
• Best practices (again)

(It's probably a good idea to provide more than one location where docs may be accessible from when it would make natural sense for them to be located there.)

Community

• Mail list
• Blog
• Social media
• Blogs of community members
• "News sites" (LFE on Reddit and Hacker News)

History

Lisp is nearly unique in the PL world as having such a long and Rich history. We've got some materials gathered -- we should continue to make this one of the features of the documentation site (not only Lisp, but Erlang as well).

Other Media

• Presentations (slide decks)
• Videos
• Audio Interviews/Podcasts
• Screencasts

As a list, this would be spread out on a page with important information lost "below the fold" -- so we should have a grouping of topics towards the top in something like a jumbotron. Additional cues for what's available can be giving in a new, docs-site-wide menu, which would also highlight the major topic areas. (The Github Docs site has a good example of this.)

[oubiwann]

We need to present just 2 or 3 of these to the site visitor initially, the most important ones. Here's my ranking of the importance for the sections listed above, in this given context (that of web visitors):

1. Learning LFE
2. Reference
3. Building Applications
4. Tooling
5. Community Libraries
6. Contributing
7. Community Resources
8. Other Media
9. History

As such, my gut is to just put links to "Learning LFE" and "Language Reference" on the front of the docs page, and then have the rest be easily discoverable. Hrm, it would probably be a good idea to indicate which of these would be in the form of traditional docs (and thus versioned for LFE releases) and which would just be regular content maintained regardless of LFE version.

Versioned Docs

• Learning LFE
• Language Reference
• Building Applications
• Tooling
• Contributing (instructions would change for this, based on new LFE features and tooling)

Regular Content

• LFE X (LFE Exchange/Community Libraries)
• Community Resources
• Other Media
• History

[oubiwann]

Navigation Menus

These are proposed...

Top Nav Menu

This would be at the top of the page.

• Docs
• Resources
• Community
• Blog
• Main Site

Sub-nav for "Reference" Section

Have a title, off to the left, of "LFE Docs" (this would be where the Github docs "API" links are). Then with the following sub-menu items:

• Getting Started
• Reference
• Creating Apps
• Tooling
• Contributing
• Other Versions

[oubiwann]

Next, we need to choose the links for the bottom/footer. Github uses the following:

• Terms
• Privacy
• Security
• Contact
• (split with logo)
• Status
• Training
• Shop
• Blog
• About

This is a good place for generally useful but possibly minor links. The sorts of things that people will be looking for and expect to find in a footer. Maybe these?

• Tutorials
• Presentations
• History
• LFE Exchange
• (split with logo)
• Contributing
• Issues
• Blog
• Twitter

[oubiwann]

The OpenStack docs identify the following for their project:

Column 1

• Install Guides
• API Guides
• Configuration Guides
• Admin Guides

Column 2

• User Guides
• Contributor Guides
• Training Guides

Admittedly, very different projects with very different focus, but some good organization for their particular needs and audience.

[oubiwann]

Addressing this task:

Identify which categories have content that should be versioned

We're going to version the whole site.

[oubiwann]

Addressing this task:

Decide upon bottom-nav menu items

The current v3 demo page uses the following in the footer:

• Tutorials
• Presentations
• History
• LFEX
• Contributing
• Docs
• Tickets
• Blog
• Twitter

[oubiwann]

Addressing this task:

Decide upon top-nav menu items

Let's start with these:

• Version: (default) drop-down
• Getting Started
• Reference
• Community
• Blog
• LFE (Main Site)

[oubiwann]

Addressing this task:

Identify major documentation categories

The lfe-deprecated/docs3#2 issue is working with these:

1. Learning LFE
2. Reference
3. Building Applications
4. Tooling
5. LFE Libraries
6. Getting Involved
7. Community Resources
8. History

[oubiwann]

This is pretty much done for now: lfe-deprecated/docs3@70703c8

We can update as necessary later.