Following up on the action item for the infra-docs/SOP migration from the wiki to git I was wondering what opinions folks had on these two markup mechanisms:
markdown
Restructured Text
Suggestions include:
1. having each page be plain text and have the following format: Title: blah Summary: blah blah blah
Body goes here
Then having a commit hook for the git repo generate a simple index of the above for browsing on a web site.
2. Just put the txt files in a dir and let you browse based on filename and be done with it. - since a lot of us are going to just use git grep ANYWAY, just roll with it.
I'm inclined toward simple and add complexity as we go.
-sv
On Wed, 03 Aug 2011 12:34:12 -0400 seth vidal skvidal@fedoraproject.org wrote:
Following up on the action item for the infra-docs/SOP migration from the wiki to git I was wondering what opinions folks had on these two markup mechanisms:
markdown
Restructured Text
Suggestions include:
- having each page be plain text and have the following format:
Title: blah Summary: blah blah blah
Body goes here
Then having a commit hook for the git repo generate a simple index of the above for browsing on a web site.
- Just put the txt files in a dir and let you browse based on
filename and be done with it. - since a lot of us are going to just use git grep ANYWAY, just roll with it.
I'm inclined toward simple and add complexity as we go.
Me too, so 2 seems better at first and if we can't find things we can add an index as per 1 when needed.
I'd like to keep the headings that we have on the wiki page too:
== Contact Information == Owner:
Contact:
Location:
Servers:
Purpose:
And some further stuff I wrote up, which is pretty obvious:
Migration plan ==============
For each SOP:
1. Copy the content out of the wiki version into a text file.
2. Update or clean up any wording that should be cleaned up or changed.
3. Commit to new repo and push.
4. Change the wiki page to note that the SOP has been converted and redirect to a wiki page that explains about the git repo and how to access it and/or a link to that particular sop.
And finally a question:
Currently, our SOP's are in the wiki, and anyone in cla_done can edit them. Should we carry this over to the new repo? As long as it notifies us on commits I am just fine with that, but is that possible if it's on lockbox01?
kevin
On Wed, 2011-08-03 at 11:16 -0600, Kevin Fenzi wrote:
Me too, so 2 seems better at first and if we can't find things we can add an index as per 1 when needed.
I'd like to keep the headings that we have on the wiki page too:
== Contact Information == Owner:
Contact:
Location:
Servers:
Purpose:
And some further stuff I wrote up, which is pretty obvious:
Migration plan
For each SOP:
Copy the content out of the wiki version into a text file.
Update or clean up any wording that should be cleaned up or changed.
Commit to new repo and push.
Change the wiki page to note that the SOP has been converted and redirect to a wiki page that explains about the git repo and how to access it and/or a link to that particular sop.
I'll add this to the README for the repo
Currently, our SOP's are in the wiki, and anyone in cla_done can edit them. Should we carry this over to the new repo?
IMO - no. If you want to work on an SOP I don't feel bad at you having to be at least fi-apprentice.
As long as it notifies us on commits I am just fine with that, but is that possible if it's on lockbox01?
It's not sine cla_done won't be able to login.
-sv
On Wed, 03 Aug 2011 13:27:31 -0400 seth vidal skvidal@fedoraproject.org wrote:
I'll add this to the README for the repo
Sounds good.
Currently, our SOP's are in the wiki, and anyone in cla_done can edit them. Should we carry this over to the new repo?
IMO - no. If you want to work on an SOP I don't feel bad at you having to be at least fi-apprentice.
As long as it notifies us on commits I am just fine with that, but is that possible if it's on lockbox01?
It's not sine cla_done won't be able to login.
Yeah. ok, fi-apprentice+ it is then...
kevin
On Wed, 2011-08-03 at 12:19 -0600, Kevin Fenzi wrote:
On Wed, 03 Aug 2011 13:27:31 -0400 seth vidal skvidal@fedoraproject.org wrote:
I'll add this to the README for the repo
Okay - I've made the repo:
git clone /git/infra-docs
on lockbox01.fedoraproject.org
you must be a member of sysadmin or fi-apprentice to push back to it.
it outputs the docs to: http://infrastructure.fedoraproject.org/infra/docs/
there is a readme there.
I ported the kickstart SOP as a test, I used links -dump + a little regex search/replace. Simple simple.
The git repo in /git/infra-docs has fancy-pants extended acls on it.
That took a little doing - but works pretty well.
-sv
On Wed, 03 Aug 2011 15:23:51 -0400 seth vidal skvidal@fedoraproject.org wrote:
On Wed, 2011-08-03 at 12:19 -0600, Kevin Fenzi wrote:
On Wed, 03 Aug 2011 13:27:31 -0400 seth vidal skvidal@fedoraproject.org wrote:
I'll add this to the README for the repo
Okay - I've made the repo:
git clone /git/infra-docs
on lockbox01.fedoraproject.org
you must be a member of sysadmin or fi-apprentice to push back to it.
it outputs the docs to: http://infrastructure.fedoraproject.org/infra/docs/
there is a readme there.
I ported the kickstart SOP as a test, I used links -dump + a little regex search/replace. Simple simple.
The git repo in /git/infra-docs has fancy-pants extended acls on it.
That took a little doing - but works pretty well.
Excellent. Thanks!
I setup a easyfix ticket asking apprentice folks to look at converting SOP's. Of course anyone who has time/energy to do so should feel free to convert them over.
kevin
On Wed, Aug 03, 2011 at 12:34:12PM -0400, seth vidal wrote:
Following up on the action item for the infra-docs/SOP migration from the wiki to git I was wondering what opinions folks had on these two markup mechanisms:
markdown
Restructured Text
I like restructured text because I use it extensivel for my documentation but I don't think that it or any other generic markup language is going to be a good fit here. The problem is that you can't just ignore features. If we wrote in restructured text or markdown and wanted to convert to html the parsers would choke on invalid syntax or format things in somehwat surprising ways.
Suggestions include:
- having each page be plain text and have the following format:
Title: blah Summary: blah blah blah
Body goes here
Then having a commit hook for the git repo generate a simple index of the above for browsing on a web site.
- Just put the txt files in a dir and let you browse based on filename
and be done with it. - since a lot of us are going to just use git grep ANYWAY, just roll with it.
3. Write/find a minimal txt2html parser that just understands headings and has a hyperlink format and use that to create html versions of the txt files. (with everything else in <pre></pre>)
4) Agree to follow some format for headings/hyperlinks that look good as text and we could use with a parser at a later date.
I kinda like 4) and I'd say just keep the wiki format for headings and links might be the easiest way to transition the docs.
-Toshio
infrastructure@lists.fedoraproject.org
-
Kevin Fenzi -
Seth Vidal -
Toshio Kuratomi