Denny wrote on the mailing list,
I am thinking it might be easier if we all could work with this ourselves. Could you recommend a tutorial for working with this markdown stuff?
Clearly we should do this. But we should go beyond explaining markdown. We should allow authors to edit files in the repo directly, and we should have docs explaining to users how to work on their own posts.
Given that not all authors are familiar with git, branches, merges, github, forks, and pull requests, we can explain how to use github's or prose.io's web interfaces for adding and editing files. We should add this documentation before adding documentation on using git.
We also need docs for explaining the ocs blog conventions for which pelican fields are required, how they are used, and what they are used for as well as provide example markdown files with comments explaining these things. Without this, documentation on adding files wouldn't be useful.
In order to avoid requiring users to understand branching and forks out of the gate, I think we could work around this by creating a draft branch and setting it as the default branch in the settings.
I think when authors use the web ui to add and edit files, those files will get added to the default branch. I have not tested this. I know that when I git pull repos that my local repo starts off on the default branch.
I do not have time to test this, but I wanted to open the issue up for discussion.
Denny wrote on the mailing list,
Clearly we should do this. But we should go beyond explaining markdown. We should allow authors to edit files in the repo directly, and we should have docs explaining to users how to work on their own posts.
Given that not all authors are familiar with git, branches, merges, github, forks, and pull requests, we can explain how to use github's or prose.io's web interfaces for adding and editing files. We should add this documentation before adding documentation on using git.
We also need docs for explaining the ocs blog conventions for which pelican fields are required, how they are used, and what they are used for as well as provide example markdown files with comments explaining these things. Without this, documentation on adding files wouldn't be useful.
In order to avoid requiring users to understand branching and forks out of the gate, I think we could work around this by creating a draft branch and setting it as the default branch in the settings.
I think when authors use the web ui to add and edit files, those files will get added to the default branch. I have not tested this. I know that when I git pull repos that my local repo starts off on the default branch.
I do not have time to test this, but I wanted to open the issue up for discussion.