Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Content Restructuring #3

Closed
jugglinmike opened this issue Jul 19, 2016 · 1 comment
Closed

Content Restructuring #3

jugglinmike opened this issue Jul 19, 2016 · 1 comment

Comments

@jugglinmike
Copy link
Owner

Based on my experience writing content, I'd like to change the terminology I
use for the course's structure. Currently, the course is divided into
"chapters," each with a number of "sections."

  • Chapter 1
    • Section 1
    • Section 2
  • Chapter 2
    • Section 1
    • Section 2

One issue here is that the so-called "sections" will be rendered as separate
web pages, meaning that a given "chapter" will encompass multiple web pages.
The second is that "section" has a well-defined meaning in the context of HTML
documents, and a 1-to-1 relationship between "section" and "document" eschews
that meaning.

Instead, I'd like to organize the content as four "parts," each with a number
of "chapters." Then each "chapter" could have any number of "sections."

  • Part I
    • Chapter 1
      • section
      • section
      • section
    • Chapter 2
      • section
      • section
  • Part II
    • Chapter 3
      • section
      • section
    • Chapter 4
      • section
      • section
      • section

Note also that chapter numbers are assigned without regard for "part"
membership, as in print publications.

Besides making the structure more familiar to a general audience, I'm motivated
by the desire to modularize the soon-to-be "chapters." I want to reformat this
content to be agnostic of numbers. This will lower friction when re-arranging
and extending, especially when it comes to creating internal references (for
example, consider a reference scheme that refers to the "About the Course"
chapter via chapter:about-course versus on that does so via
part1:chapter2:about-course).

I've been looking at "Learn SSH" and "Learn Ansible," and I believe that
material would fit this structure if the "Part" distinction were considered
optional.

@jugglinmike
Copy link
Owner Author

Okay, I've completed the restructuring. The src/material directory is now a
whole lot more flat:

$ tree -L 1 src/material/
src/material/
├── about-course
├── command-invocation
├── file-mgmt
├── file-system
├── history
├── index.md
├── process-bounds
├── process-mgmt-1
├── process-mgmt-2
├── setup
├── sudo
└── vagrant

Unfortunately, removing chapter ordering information also makes it very
difficult to review the content. I took some time yesterday and today to
implement an early build process for the site. That's now in master with a
simple Makefile to formalize the process for generating the content and
publishing it to the "gh-pages" branch of this repository.

I'm closing this issue as "resolved" because I'm in charge around here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant