[FOLIO-645] Design improved url-space and navigation content dev.f.o phase 2 Created: 31/May/17  Updated: 12/Nov/18  Resolved: 04/Apr/18

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Task Priority: P3
Reporter: David Crossley Assignee: David Crossley
Resolution: Done Votes: 0
Labels: devweb
Remaining Estimate: Not Specified
Time Spent: 1 day, 5 hours, 45 minutes
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-646 Implement improved navigation dev.f.o... Closed
relates to FOLIO-643 Improve navigation and layout dev.f.o... Closed
Sprint:

 Description   

Assess the current situation and envisage some future needs.



 Comments   
Comment by David Crossley [ 26/Jun/17 ]

Added doc/#guides sections as topic groups to assist with navigation.

These topic sections also enable linking to there, from a summary navigation menu.

Comment by David Crossley [ 26/Jun/17 ]

Method:
Think of a need for a doc. Try to add it to relevant sections. If not, then add it to "Others". Later make new sections. If needed, rename others.

Comment by Patricia DeStefano [ 23/Aug/17 ]

Investigating a custom jekyll theme that incorporates both the common nav bar in FOLIO-714 Closed and a developer navigation bar.

Comment by David Crossley [ 12/Dec/17 ]

It is difficult to resolve this via Jira, but lets try here first. Then perhaps a Zoom discussion could finalise it.

Soon i will attempt to describe what we currently have, both in master and in the current PoC branch.
List the current set of documents.

Then we could define the purpose and structure of about seven or eight top-level directories.

See where those current documents fit into that, and try to anticipate some future ones.

Rearrangement of docs is disruptive. It would be good to only do it once.

Comment by David Crossley [ 12/Dec/17 ]

Patricia DeStefano would you please say what you see as the difference between "guidelines" and "guides".

Also i am wondering if the "devtools" stuff might be able to go into those areas.

Comment by Patricia DeStefano [ 12/Dec/17 ]

Guides - discuss key topics and concepts
Tutorials - process step by step
Guidelines - rules to follow

The content files in the POC are divided into directories according to what type of content it is. So, in the POC, right now we have 8 categories for the documents - Getting Started, Reference, Code, Guides, Download, Tutorials, Tools and Guidelines. Each category has a corresponding directory in the POC - _guidelines, _reference…etc So, all markdown/content files for each type of content would go in the proper directory and appear in the generated website in the corresponding section.

There is a category in the POC call Tools. If you are speaking of what I am thinking about, I would put devtools in Tools.

Comment by David Crossley [ 14/Dec/17 ]

Actually, i was wondering if we could dispense with the "devtools". Those docs may be just another type of "guide".

There is a comment in FOLIO-817 Closed about perhaps being too many top nav sections.

Comment by David Crossley [ 14/Dec/17 ]

On the other hand there are some existing documents (e.g. "/community/cla-process" and "/about/thanks" and others) that might not fit into the "guidelines" or "guides" structure. Also i reckon that we will need various separate "troubleshooting" and "faq" type of documents.

Comment by David Crossley [ 14/Dec/17 ]

It would be good to have readable and consistent URLs (e.g. "primer-develop-backend") i.e. using dash "-" between words. Rather than for example "tutorials/clonebuildexploreokapi".

Perhaps better to have "/guides/" rather than "/devguides/". The whole site is about "dev" so that seems superfluous.

Comment by David Crossley [ 14/Dec/17 ]

I expect that we will have multiple "tutorials". Would they have separate sub-directories, e.g. "/tutorials/curriculum/lesson-1/" and "/tutorials/curriculum/lesson-2/" and then another at "/tutorials/another-topic/lesson-1/" etc.

Comment by David Crossley [ 14/Dec/17 ]

We will being having lots of "guides". The current dev.folio.org/doc/#guides makes an attempt to group guides and other documents into a set of "topic groups". Can you see another way to have a "guide to guides"?

Comment by David Crossley [ 18/Dec/17 ]

Patricia DeStefano, and others, are we able to resolve the abovementntioned comments?

Comment by Patricia DeStefano [ 18/Dec/17 ]

David Crossley A basic structure (tutorials, guides, etc) is in the POC and I am working to add the additional left hand navigation of that structure into the theme POC. We can definitely fine tune directory names, sections and which docs are in each section. The theme makes shuffling things and renaming fairly easy.

Comment by David Crossley [ 19/Dec/17 ]

We need to resolve various stuff related to the actual re-arrangement of the documents. Trying to think about this early. Also some items might have impact for either theme (e.g. the questions above about sub-directories of "tutorials" and "guides").

Comment by David Crossley [ 17/Jan/18 ]

See a demonstration of "separate tutorials in sub-directories" at FOLIO-978 Closed .

Comment by David Crossley [ 04/Apr/18 ]

This re-arrangment is now done. See the notes in FOLIO-646 Closed .

Generated at Thu Feb 08 23:07:18 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.