clean up hip_hack_howto repo

[arlin]

The idea is to get this in shape when reviewers and eventually the public look at it. Most of the clutter is at the top level. This can be trashed, or put in a folder labeled "extras" or "archive" or "outs".

[rvosa]

I've been working on decluttering the repo according to a simple structure explained in the root-level README.md. This has not addressed the issue of useless clutter, it's just been swept under the rug - but I had to do this to be able to do #51 somewhat sensibly within this same repo.

[rvosa]

By the way, can we move the guidance doc into this repo? We now have things on github, google drive, and dropbox. I would like to at least get rid of dropbox.

[arlin]

Here is the problem. I envision these being printed and put in a sheet-protector and carried in hand by facilitators and organizers. So, I consider it one of the requirements that this be a succinct printable doc-- each section has to be limited to 2 sides of a sheet. This is the only reason I was using Word, which meant that I had to use dropbox. I can't make a succinct printable document using Google docs, Markdown, or HTML. I need precise control over formatting. The obvious text options are RTF or LaTeX. I imagine that an experienced LaTeX user could simply grab the text and reformat it by hand, because it is only using a few formatting elements. Do you want to try? I don't usually use LaTeX so it would take me some time to set up, learn, and do this.

[rvosa]

How precise is the control that we really need? Might it not be possible to do it in markdown and then convert to pdf with pandoc (say)? I am not a LaTeX guru either and I suspect it might be overkill.

On Thu, Nov 5, 2015 at 3:31 PM, Arlin Stoltzfus notifications@github.com wrote:

Here is the problem. I envision these being printed and put in a sheet-protector and carried in hand by facilitators and organizers. So, I consider it one of the requirements that this be a succinct printable doc-- each section has to be limited to 2 sides of a sheet. This is the only reason I was using Word, which meant that I had to use dropbox. I can't make a succinct printable document using Google docs, Markdown, or HTML. I need precise control over formatting. The obvious text options are RTF or LaTeX. I imagine that an experienced LaTeX user could simply grab the text and reformat it by hand, because it is only using a few formatting elements. Do you want to try? I don't usually use LaTeX so it would take me some time to set up, learn, and do this.

— Reply to this email directly or view it on GitHub https://github.com/arlin/hip_hack_howto/issues/50#issuecomment-154076151 .

[arlin]

After checking out some options, my impression is that LaTeX would be a really nice approach for us. There are existing online tools for shared editing, with built-in rendering and github integration. That is, you pull the file directly out of github, and edit it in the left pane while you view the rendering in the right pane. I was able to do a 2-page section in 45 minutes. I could do the rest of it in another 45 minutes, I think.
guidelines_template.pdf

[rvosa]

Great! I guess with what we want to go in these docs (i.e. no figures, references, formulae) the latex is not that difficult.

Op Fri, 6 Nov 2015 om 23:38 schreef Arlin Stoltzfus < notifications@github.com>

After checking out some options, my impression is that LaTeX would be a really nice approach for us. There are existing online tools for shared editing, with built-in rendering and github integration. That is, you pull the file directly out of github, and edit it in the left pane while you view the rendering in the right pane. I was able to do a 2-page section in 45 minutes. I could do the rest of it in another 45 minutes, I think.

guidelines_template.pdf https://github.com/arlin/hip_hack_howto/files/29261/guidelines_template.pdf

— Reply to this email directly or view it on GitHub https://github.com/arlin/hip_hack_howto/issues/50#issuecomment-154564700 .

[arlin]

Done with LaTeX conversion, and very happy with results (except I could not get one crucial section to fit in 2 pages).

[arlin]

@rvosa, I'm reviewing this ticket. Thanks, the new organization is much cleaner. This is good as an archive of our project (e.g., with a dir for our rough drafts and discussions at the top level). How can we make it the go-to site for resources on the NESCent hackathon model? Visitors will come here (whether or not they have read the paper first), because (1) they are organizers and they want to get the get the guidelines and templates to use, or (2) they are researchers and they want to get the systematic data, or (3) they are curious and want to find out more.

[rvosa]

I think the way to make it the go-to-site is by:

1. writing readable, correct README's that guide visitors through the repo
2. assigning a Zenodo DOI to this repo, which we advertise in our manuscript

[rvosa]

I didn't fully understand how far you wanted to take this repo until you said it at the telecon: you also want to make it a static website, correct? I think these same steps more or less apply, especially as regards the writing of the README(s) because github tries to be helpful by converting at least the base README to a static page (with nice styling) once you start using the gh-pages functionality.

[arlin]

Following your suggestion, I tried to rewrite the README with a broader audience in mind. Please take a look.

But ultimately I think we don't want to depend on clunky Markdown. Wouldn't it be better to develop our outward-facing content using the wiki functionality?

[arlin]

BTW, I'm about to transfer this to NESCent, so it might disappear.

[rvosa]

I don't think we should choose between Markdown and Wiki. Doesn't it make the most sense to make the front-facing README as readable as possible, add a link to the wiki, and then turn the repo into a website automagically?