[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: |
|
||||||||||||
| 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: |
| Comment by Patricia DeStefano [ 23/Aug/17 ] |
|
Investigating a custom jekyll theme that incorporates both the common nav bar in
|
| 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. 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 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
|
| 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
|
| Comment by David Crossley [ 04/Apr/18 ] |
|
This re-arrangment is now done. See the notes in
|