Write Guidelines for Markdown structure

jmatsushita commented 8 years ago

@Coccodrillo @poser @houndbee

Here's some thoughts about the approach to exporting existing content in a "content as code"

Structure

One of the driving principles is to focus on AX (the Author's Experience). Therefore the content should be in a simple file structure that strongly reflect the organisation of the content in "its natural habitat" i.e. where it's meant to be displayed in the end. This will make it easy to find content. Here's an example of this with Open Mentoring

The content on the app here :

The file structure on prose/github is very similar:

The UX could be improved more by dealing with titles better. (Here Dealing with Emergencies is practice-1-emergencies and Getting Started is 0-getting-started).

Here's an example of how the file structure is on the Open Mentoring app:

/                           # root folder

  en/                       # top level folder for each language

    resources/              # Static or dynamic content that are not part of exchanged 
                            # content (they hold information but are not meant to be 
                            # structured like learning content)

    topics/                 # Contains Topics.

      a-topic/              
      another-topic/        # Contains Units

        a-unit/
        another-unit/       # Contains Stacks

          1-intro.md        # Example Stack.
          1-intro-hrd.md    # Example Stack for the hrd profile.
          ...

Granularity

Another important consideration is how the content is broken down. Currently in Open Mentoring the approach is to have "stacks" be Markdown files. Read more about in the openmentoring MODEL.md doc.

Multiple stacks are then aggregated into single pages on the web:

And an individual stack (here under the Scenario heading) is actually split (using <br> as the token right now) into cards on the mobile app like this:

And this is what it looks like on Prose

The source Markdown for this is here:

https://github.com/iilab/openmentoring-content/edit/master/en/topics/practice-1-emergencies/1-seeking-help/2-scenario.md

What I'd like is to maintain a AX focused approach here, but this probably means allowing authors to switch context depending on what they want to look at (web view, mobile view,...). Right now there's a trade off in Open Mentoring in order to make it easy

Open Questions

Currently the openmentoring-curation layer also allows to specify metadata that will be inherited by the children files, which helps DRY for instance the source metadata key in the index.md file here will be applied to all the stacks in the same folder.

Also to avoid having to add frontmatter metadata (or companion metadata files - like having a content.md with only markdown and content.json or content.yaml with only metadata) openmentoring uses keywords in file names to create metadata keys (which is also described in the MODEL.md file).

There will be cases where particular pieces of content are reused in different places in the app. My current thinking is to have these reusable components included via symlinks for content that's in a file, or some kind of block level include syntax (see middlematter discussion in #12) which could also work for including remote content.

The usability of this completely depends on building on top of a content authoring tool like prose, developing plugins to deal with middlematter, symlinks or remote includes in a way that is natural for authors.

seamustuohy commented 8 years ago

Check out http://archieml.org: a structured text format optimized for human writability.

poser commented 8 years ago

Nice. Purpose built and oh so minimal. Archieml is definitely plucking at my heartstrings...

On the other end of the "mediated experience" continuum, Carol stumbled upon PubPub last week. At the moment, it's heavily optimized for traditional documents, but it seems to have a lot going for it. Think collaborative, Markdown-based medium.com. It's supposed to be "open sourced within the month" but the developer seems quite responsive.

And those includes (e.g. [[image: source=2falogopng, align=left, size=small, caption="FreeOTP"]]) might be enough to accommodate a lot of non-text structures we need for guides, curricula, apps, etc. Assuming they are extensible. And assuming this thing is built on top of git.

Anyway, my username is 'poser' and Carol's is 'Cee Dub'. We can add you as collaborators if you track us down. I added an orphaned, half-written Security in-a-Box guide for testing and Carol added something from LevelUp.

jmatsushita commented 8 years ago

Good chatting earlier about structure @poser

Here's few things that came up and could be of interest for similar use cases for re-usable bits of content (snippets) being included (transcluded) into documents.

The specific use case here was to have the same document (let's call it the master document), contextualised with different snippets. In that case:

It would make sense for the snippets to live close to where they are used.
Snippets link in the master document could be relative to pick up the contextualised snippets.

A few things I've added with regards to linking:

a snippets folder ([[snippet_01]] ==> [[snippets/01]] which I think is
descriptive names for snippets ([[snippets/01]] ==> [[snippets/story]]).

en/
  master/
    a_guide/
      index.md              # The master document with relative includes such as [[snippets/story]]
      snippets/
        story.md
        example.md
  another_context/
    a_guide/
      index.md              # Just the metadata pointing to en/master/a_guide/index.md
      snippets/
        story.md            # The story contextualised to another_context
        example.md      # The example contextualised to another_context

I've added PubPub in the discussion on editors #5 and I'll muse about transclusion in #12 and maybe will create a new issue about which ways to extend what.

@elationfoundation I had seen ArchieML before and did really like the more resistant white-spacing aspect and generally resilient approach! Definitely to add on the list of supported metadata formats for contentascode (I've created an issue for that #29) !

jmatsushita commented 8 years ago

After looking at a few, I prefer the Hercules Markdown transclusion syntax which is :[text](file.md)

But here are a few for reference:

MultiMarkdown {{some_other_file.txt}} http://fletcher.github.io/MultiMarkdown-4/transclusion https://github.com/jgm/pandoc/issues/81
Marked2 <<[sections/section1.md] http://marked2app.com/help/Multi-File_Documents.html http://marked2app.com/help/Special_Syntax.html#fileincludes
LeanPub <<[Code title](folder/filename) https://leanpub.com/help/manual#leanpub-auto-code-samples

What I like about I like about :[text](file.md):

It's more terse than the alternatives above.
It looks more like Markdown
It degrades well as most parsers will treat it like a basic link.

In addition the format used by Hercules https://github.com/jamesramsay/hercule which is also including things like providing context :[Required Ingredient](cucmber.mson required:"required") and seems well tested and maintained, and aimed also at API Blueprint which has pretty strong integrity needs. Plus we can probably use the library to deal with assembly.

seamustuohy commented 8 years ago

Have you checked out restructuredText. I just started playing with it on a project and then watched this video and think it might have built in a lot of the internal metadata and semantic structure that is required in your comments. https://www.youtube.com/watch?v=eWNiwMwMcr4

iilab / contentascode