{"action":"created","issue":{"url":"https://api.github.com/repos/iilab/contentascode/issues/25","repository_url":"https://api.github.com/repos/iilab/contentascode","labels_url":"https://api.github.com/repos/iilab/contentascode/issues/25/labels{/name}","comments_url":"https://api.github.com/repos/iilab/contentascode/issues/25/comments","events_url":"https://api.github.com/repos/iilab/contentascode/issues/25/events","html_url":"https://github.com/iilab/contentascode/issues/25","id":136129845,"number":25,"title":"Write Guidelines for Markdown structure","user":{"login":"jmatsushita","id":356097,"avatar_url":"https://avatars.githubusercontent.com/u/356097?v=3","gravatar_id":"","url":"https://api.github.com/users/jmatsushita","html_url":"https://github.com/jmatsushita","followers_url":"https://api.github.com/users/jmatsushita/followers","following_url":"https://api.github.com/users/jmatsushita/following{/other_user}","gists_url":"https://api.github.com/users/jmatsushita/gists{/gist_id}","starred_url":"https://api.github.com/users/jmatsushita/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jmatsushita/subscriptions","organizations_url":"https://api.github.com/users/jmatsushita/orgs","repos_url":"https://api.github.com/users/jmatsushita/repos","events_url":"https://api.github.com/users/jmatsushita/events{/privacy}","received_events_url":"https://api.github.com/users/jmatsushita/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":4,"created_at":"2016-02-24T17:29:24Z","updated_at":"2016-04-12T23:54:23Z","closed_at":null,"body":"@Coccodrillo @poser @houndbee\r\n\r\nHere's some thoughts about the approach to exporting existing content in a \"content as code\" \r\n\r\n## Structure\r\n\r\nOne 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\r\n\r\nThe content on the app here : \r\n\r\n![image](https://cloud.githubusercontent.com/assets/356097/13294228/4e49d124-db23-11e5-9d54-be981aa26aee.png)\r\n\r\nThe file structure on prose/github is very similar:\r\n\r\n![image](https://cloud.githubusercontent.com/assets/356097/13294051/8577c1e8-db22-11e5-99e9-f68cc1f21776.png)\r\n\r\nThe 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*).\r\n\r\nHere's an example of how the file structure is on the Open Mentoring app:\r\n\r\n\r\n```\r\n/                           # root folder\r\n  \r\n  en/                       # top level folder for each language\r\n\r\n    resources/              # Static or dynamic content that are not part of exchanged \r\n                            # content (they hold information but are not meant to be \r\n                            # structured like learning content)\r\n\r\n    topics/                 # Contains Topics.\r\n\r\n      a-topic/              \r\n      another-topic/        # Contains Units\r\n\r\n        a-unit/\r\n        another-unit/       # Contains Stacks\r\n\r\n          1-intro.md        # Example Stack.\r\n          1-intro-hrd.md    # Example Stack for the hrd profile.\r\n          ...\r\n\r\n```\r\n\r\n\r\n## Granularity\r\n\r\nAnother 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](https://github.com/iilab/openmentoring-content/blob/master/MODEL.md).\r\n\r\nMultiple stacks are then aggregated into single pages on the web: \r\n![image](https://cloud.githubusercontent.com/assets/356097/13294116/ced5d62c-db22-11e5-9c41-341e57a9264a.png)\r\n\r\nAnd 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:\r\n\r\n![image](https://cloud.githubusercontent.com/assets/356097/13294235/554f8f7c-db23-11e5-925d-99b5c33bcdd8.png)\r\n\r\nAnd this is what it looks like on Prose\r\n\r\n![image](https://cloud.githubusercontent.com/assets/356097/13294147/013a4864-db23-11e5-8a69-2af0e15208cd.png)\r\n\r\nThe source Markdown for this is here:  \r\n\r\nhttps://github.com/iilab/openmentoring-content/edit/master/en/topics/practice-1-emergencies/1-seeking-help/2-scenario.md\r\n\r\nWhat 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\r\n\r\n## Open Questions\r\n\r\nCurrently 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](https://github.com/iilab/openmentoring-content/blob/master/en/topics/practice-1-emergencies/0-getting-started/index.md) will be applied to all the stacks in the same folder.\r\n\r\nAlso 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](https://github.com/iilab/openmentoring-content/blob/master/MODEL.md) file).\r\n\r\nThere 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. \r\n\r\nThe 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. "},"comment":{"url":"https://api.github.com/repos/iilab/contentascode/issues/comments/209155154","html_url":"https://github.com/iilab/contentascode/issues/25#issuecomment-209155154","issue_url":"https://api.github.com/repos/iilab/contentascode/issues/25","id":209155154,"user":{"login":"elationfoundation","id":1226247,"avatar_url":"https://avatars.githubusercontent.com/u/1226247?v=3","gravatar_id":"","url":"https://api.github.com/users/elationfoundation","html_url":"https://github.com/elationfoundation","followers_url":"https://api.github.com/users/elationfoundation/followers","following_url":"https://api.github.com/users/elationfoundation/following{/other_user}","gists_url":"https://api.github.com/users/elationfoundation/gists{/gist_id}","starred_url":"https://api.github.com/users/elationfoundation/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/elationfoundation/subscriptions","organizations_url":"https://api.github.com/users/elationfoundation/orgs","repos_url":"https://api.github.com/users/elationfoundation/repos","events_url":"https://api.github.com/users/elationfoundation/events{/privacy}","received_events_url":"https://api.github.com/users/elationfoundation/received_events","type":"User","site_admin":false},"created_at":"2016-04-12T23:54:23Z","updated_at":"2016-04-12T23:54:23Z","body":"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"}}