7 ms·

Gutenberg: Dynamic README generator with mixins for GitHub

33 points by svoroval 13y ago

straykov 13y ago
Awesome!
matthiasv 13y ago
So, for the simplest tasks such as writing a README you need a Ruby gem these days? Or is it some satire which I didn't get yet? (Just to clarify my position: I am all for automatizing daunting tasks as much as possible, but this seems to be a little far-fetched.)
- benaiah 13y ago
  It doesn't seem to be useful so much as a way to make README writing easier, but rather as an easier and more modular way to keep it updated. This is important - stale docs are a PITA for anyone trying to use a library, and it's very easy to let them fall by the wayside.
  - svoroval 13y ago
    Sure! You’ve got the idea.
  - ret 13y ago
    I agree, but why not use existing program like M4.
    - svoroval 13y ago
      Because it is not designed for this purpose?
- svoroval 13y ago
  Not really far-fetched. Look at Sinatra README for example: https://github.com/sinatra/sinatra https://github.com/sinatra/sinatra There are 11 versions of Sinatra’s README which don’t share any general templates. They should be manually edited after each release. This is kind of thing that needs automatization. Plus, it is much easier to inject badges by a mixin, not by copypasting and manually changing some elements from your old READMEs.
  - matthiasv 13y ago
    Good point about those many versions. It's actually the first time that I've seen multiple READMEs in one project.
- sanderjd 13y ago
  Well, no, nobody said you need a library to help you write your README, but if you get tired of writing the same structure or making the the same updates over and over again, you can use this to automate some of that process if you so desire. Seems pretty nifty to me, though I may well never use it. I really don't understand the mindset that takes people from "hey look somebody wrote a free piece of software I can use if I want" to "what, now I need to use yet another piece of software for something?"
  - matthiasv 13y ago
    > I really don't understand the mindset that takes people from "hey look somebody wrote a free piece of software I can use if I want" to "what, now I need to use yet another piece of software for something?" It's not that I stop people from doing things they want to do. I just wanted to point out that something seemingly simple as writing a README usually does not require yet another tool that has to be learned and – being a dependency – maintained.
robbfitzsimmons 13y ago
I continue to be confused about when a README is appropriate for documentation on Github, and when a wiki is preferred, as do my coworkers. (It's a minor bone of contention.) If you have this many pieces that it's hard to keep straight without a tool like Gutenberg, isn't that modularization the whole idea of a wiki?
- svoroval 13y ago
  Wiki doesn’t download with your repo. I think that’s the reason. I don’t know. I just don’t feel approriate to use Wiki for projects that are smaller than 6000 LOC, I don’t know. Maybe you’re right.
  - kanzure 13y ago
    You can always put the wiki as a submodule in the git repo since the github wikis are just git repos too: git clone git@github.com:whatever/whatever.wiki.git
    - straykov 13y ago
      And what is the format of Wiki pages?
      - anton_gogolev 13y ago
        GitHub uses Gollum [1] for wikis. [1]: https://github.com/gollum/gollum/wiki https://github.com/gollum/gollum/wiki
- sanderjd 13y ago
  I like the model of a README that shows high level project structure and common use cases, with links to specific wiki pages for more depth on a topic, and a catch-all top-level wiki link at the end.
monkeyspaw 13y ago
Gutenberg looks awesome! I have a special interest in tools that help programmers build documentation while they code. Part of the reason is that I struggle with it constantly. A shameless self-promotion here: in the last 2 days, my coworkers and I built a web app that can take markdown files and display them in a nice webpage. I just tried it out with the README file in this repo, and thought others might be interested in the result: http://www.onlinemarkdowneditor.com/docs/somu/gutenberg/README.md http://www.onlinemarkdowneditor.com/docs/somu/gutenberg/READ... There are quite a few similar projects out there, but we wanted to eliminate the extra steps of hosting and "building" documentation. However, I think something like Gutenberg looks like a very powerful way to build documentation, and it fits in nicely with the project I just worked on.
pekk 13y ago
I would have preferred to see a general solution addressing README as a special case, rather than a whole project dedicated only to README. Not interested in picking up a different tool for each kind of generated text/markup file

33 points by svoroval 13y ago

Awesome!

So, for the simplest tasks such as writing a README you need a Ruby gem these days? Or is it some satire which I didn't get yet? (Just to clarify my position: I am all for automatizing daunting tasks as much as possible, but this seems to be a little far-fetched.)

benaiah 13y ago
It doesn't seem to be useful so much as a way to make README writing easier, but rather as an easier and more modular way to keep it updated. This is important - stale docs are a PITA for anyone trying to use a library, and it's very easy to let them fall by the wayside.
- svoroval 13y ago
  Sure! You’ve got the idea.
- ret 13y ago
  I agree, but why not use existing program like M4.
  - svoroval 13y ago
    Because it is not designed for this purpose?
svoroval 13y ago
Not really far-fetched. Look at Sinatra README for example: https://github.com/sinatra/sinatra https://github.com/sinatra/sinatra There are 11 versions of Sinatra’s README which don’t share any general templates. They should be manually edited after each release. This is kind of thing that needs automatization. Plus, it is much easier to inject badges by a mixin, not by copypasting and manually changing some elements from your old READMEs.
- matthiasv 13y ago
  Good point about those many versions. It's actually the first time that I've seen multiple READMEs in one project.
sanderjd 13y ago
Well, no, nobody said you need a library to help you write your README, but if you get tired of writing the same structure or making the the same updates over and over again, you can use this to automate some of that process if you so desire. Seems pretty nifty to me, though I may well never use it. I really don't understand the mindset that takes people from "hey look somebody wrote a free piece of software I can use if I want" to "what, now I need to use yet another piece of software for something?"
- matthiasv 13y ago
  > I really don't understand the mindset that takes people from "hey look somebody wrote a free piece of software I can use if I want" to "what, now I need to use yet another piece of software for something?" It's not that I stop people from doing things they want to do. I just wanted to point out that something seemingly simple as writing a README usually does not require yet another tool that has to be learned and – being a dependency – maintained.

robbfitzsimmons 13y ago

I continue to be confused about when a README is appropriate for documentation on Github, and when a wiki is preferred, as do my coworkers. (It's a minor bone of contention.) If you have this many pieces that it's hard to keep straight without a tool like Gutenberg, isn't that modularization the whole idea of a wiki?

svoroval 13y ago
Wiki doesn’t download with your repo. I think that’s the reason. I don’t know. I just don’t feel approriate to use Wiki for projects that are smaller than 6000 LOC, I don’t know. Maybe you’re right.
- kanzure 13y ago
  You can always put the wiki as a submodule in the git repo since the github wikis are just git repos too: git clone git@github.com:whatever/whatever.wiki.git
  - straykov 13y ago
    And what is the format of Wiki pages?
    - anton_gogolev 13y ago
      GitHub uses Gollum [1] for wikis. [1]: https://github.com/gollum/gollum/wiki https://github.com/gollum/gollum/wiki
sanderjd 13y ago
I like the model of a README that shows high level project structure and common use cases, with links to specific wiki pages for more depth on a topic, and a catch-all top-level wiki link at the end.

monkeyspaw 13y ago

Gutenberg looks awesome! I have a special interest in tools that help programmers build documentation while they code. Part of the reason is that I struggle with it constantly. A shameless self-promotion here: in the last 2 days, my coworkers and I built a web app that can take markdown files and display them in a nice webpage. I just tried it out with the README file in this repo, and thought others might be interested in the result: http://www.onlinemarkdowneditor.com/docs/somu/gutenberg/README.md http://www.onlinemarkdowneditor.com/docs/somu/gutenberg/READ... There are quite a few similar projects out there, but we wanted to eliminate the extra steps of hosting and "building" documentation. However, I think something like Gutenberg looks like a very powerful way to build documentation, and it fits in nicely with the project I just worked on.

pekk 13y ago

I would have preferred to see a general solution addressing README as a special case, rather than a whole project dedicated only to README. Not interested in picking up a different tool for each kind of generated text/markup file