Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Gollum – A simple, Git-powered wiki with a sweet API and local frontend

github.com

Post reply on HN
Print view View original

11–20 of 44 posts

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#11

Post by polote »

ketzo wrote: post #2

I like the look of this a lot, particularly the support for running-from-local. I think git is such an ideal backend for something like a wiki, where multiple contributors and version history are both so important. Tangent: how do HN folks generally do technical wikis -- or really, just keep track of the technical details of your software -- in large software development organizations? My org uses Confluence for some…

There is only one way to make documention works. This is to have everyone following the same standards. This is not enough of course.

You can have different people using different tools to write it, but all those documents needs to be referenced at the same place and be searchable at least by title. There is no magic tool this is first a people/process problem

If your org has several place to find it and no strategy. Then the first step is to have a documentation strategy. That will not solve all your issues, but without it you are going to be very limited

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#13

Post by yodon »

throwaway81523 wrote: post #8

I've used gitit and it is pretty nice. Why do we need another one of these?

> gitit is pretty nice. Why do we need another one of these?

Gollum and Gitit have both been around for more than a decade. Thousands of stars, hundreds of forks, and active commit histories spanning more than ten years suggests the world views both as of value.

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#14

Post by ak217 »

If you're new to Gollum, it's the software that powers GitHub's wiki tab in the repo view.

Gollum was one of the first Markdown wikis and still is a fantastic choice for running a Git Markdown-powered wiki. I ran a number of technical documentation sites on Gollum, and one of the things that set it apart was hackability. It was easy to modify it to do very custom things based on our site's needs.

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#15

Post by chrisweekly »

ducktective wrote: post #4

Interesting! Isn't it better to couple the documentation of a project to the source (e.g. in a `docs/` sub-directory) and just use markdown?

Yep. GitLab's support for Mermaid in markdown is pretty nice. I'm looking into making my experiments with a Kroki server more official, at which point we'll have a robust platform for markdown-based, repo-internal, embedded-diagram-supporting docs.

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#16

Post by FalconSensei »

onei wrote: post #3
ketzo wrote: post #2

I like the look of this a lot, particularly the support for running-from-local. I think git is such an ideal backend for something like a wiki, where multiple contributors and version history are both so important. Tangent: how do HN folks generally do technical wikis -- or really, just keep track of the technical details of your software -- in large software development organizations? My org uses Confluence for some…

I always find Confluence to be the place where docs go to die. There's very little motivation to keep it up to date and tends to be one or two people driving it. When they move to another team or job, then it gets abandoned. The things my team uses GitHub pages for tends to do better because devs don't object too heavily to writing code comments (for generated docs), markdown (for design docs), or API specs (for API…

> I always find Confluence to be the place where docs go to die

Yeah... I'm not a big fan either. Currently in my team we just use google docs for more dynamic stuff, and have a wiki page with links to all docs. Otherwise we know that people won't bother editing

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#17

Post by NortySpock »

onei wrote: post #3
ketzo wrote: post #2

I like the look of this a lot, particularly the support for running-from-local. I think git is such an ideal backend for something like a wiki, where multiple contributors and version history are both so important. Tangent: how do HN folks generally do technical wikis -- or really, just keep track of the technical details of your software -- in large software development organizations? My org uses Confluence for some…

I always find Confluence to be the place where docs go to die. There's very little motivation to keep it up to date and tends to be one or two people driving it. When they move to another team or job, then it gets abandoned. The things my team uses GitHub pages for tends to do better because devs don't object too heavily to writing code comments (for generated docs), markdown (for design docs), or API specs (for API…

To me Confluence's problem is the not-very-relevant search, which either gives me generic blank documents that someone created as a placeholder (?!? -- I've started suffixing these with (blank)) or fails to find synonyms or related words when I can't quite come up with the exact search term (wonder if these "related words or synonyms" could be manually added...)

I'm sure it is a difficult problem but I haven't really found any good solutions other than "make really long titles that use many words to describe the content" or "Add lots of tags" and even them I'm not sure it helps or not. Does the search take into account click-through rate? Link count?

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#18

Post by ketzo »

epage wrote: post #7
onei wrote: post #3

Earlier quoted context omitted.

I always find Confluence to be the place where docs go to die. There's very little motivation to keep it up to date and tends to be one or two people driving it. When they move to another team or job, then it gets abandoned. The things my team uses GitHub pages for tends to do better because devs don't object too heavily to writing code comments (for generated docs), markdown (for design docs), or API specs (for API…

My problem with docs in repos is it isn't as smooth to edit, especially if you have to wait for reviews.

I agree that this is actually a much bigger deal than it would initially seem.

Any kind of friction is a huge problem when it comes to a task that people are already sort of reluctant to do; just the thought of "ah, fuck, I gotta get two reviews just to add a couple lines of setup instructions?" makes people way less likely to update repo docs as frequently as they need to.

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#19

Post by codazoda »

ketzo wrote: post #2

I like the look of this a lot, particularly the support for running-from-local. I think git is such an ideal backend for something like a wiki, where multiple contributors and version history are both so important. Tangent: how do HN folks generally do technical wikis -- or really, just keep track of the technical details of your software -- in large software development organizations? My org uses Confluence for some…

I use GitHub wiki’s but they’re not perfect and I think about this a lot.

I’ve been thinking about building something like Slack but for documentation instead of conversation. A git repo is a great way to store your files so that you have history, backups, and avoid vendor lock-in.

Re: Gollum – A simple, Git-powered wiki with a sweet API and local frontend

#20

Post by mojombo »

Fun to see this on HN! I originally created Gollum to power GitHub's wiki system and wanted to see if we could use Git to make our wikis more powerful AND more open. I thought it would be cool if you could just clone your GitHub wiki and modify it locally or export it to some other system if you needed, or have it all locally for an airplane trip without wifi.

Another interesting thing is that I used my Readme Driven Development method to develop it, which you can see in the Readme of the first commit: https://github.com/gollum/gollum/commit/c7875704971be998a539.... I wrote it before writing a single line of code and found it worked nicely to figure out the API and feel out the ergonomics of the text format. More on that approach here: https://tom.preston-werner.com/2010/08/23/readme-driven-deve...

Glad to see the project alive and well!

Post reply on HN