

Gutenberg: Dynamic README generator with mixins for GitHub - svoroval
https://github.com/somu/gutenberg

======
monkeyspaw
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/READ...](http://www.onlinemarkdowneditor.com/docs/somu/gutenberg/README.md)

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.

------
matthiasv
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
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.

~~~
ret
I agree, but why not use existing program like M4.

~~~
svoroval
Because it is not designed for this purpose?

------
robbfitzsimmons
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
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
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
And what is the format of Wiki pages?

~~~
anton_gogolev
GitHub uses Gollum [1] for wikis.

[1]:
[https://github.com/gollum/gollum/wiki](https://github.com/gollum/gollum/wiki)

------
pekk
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

------
straykov
Awesome!

