[HN Gopher] Gollum - A simple, Git-powered wiki with a sweet API...
___________________________________________________________________
Gollum - A simple, Git-powered wiki with a sweet API and local
frontend
Author : dsr12
Score : 109 points
Date : 2021-10-02 18:21 UTC (4 hours ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| ak217 wrote:
| 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.
| ducktective wrote:
| 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?
| chrisweekly wrote:
| 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.
| [deleted]
| throwaway81523 wrote:
| I've used gitit and it is pretty nice. Why do we need another one
| of these?
| yodon wrote:
| > 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.
| ketzo wrote:
| 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 stuff, Github pages and READMEs
| for others. It's... fine. It's not the worst I've ever seen, you
| can find some useful stuff with a little bit of work and some
| knowledge about where to look, but it's still very likely that
| whatever you're reading is either outdated or now-irrelevant.
|
| How do you (and your team) solve the challenge of keeping
| documentation actually relevant and up-to-date when there are so
| many people writing so much code, then leaving two years later?
| polote wrote:
| 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
| onei wrote:
| 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 docs). The last two in particular have become a big
| part of the design process, so it's been bought into heavily.
| Whether those stand the test of time remains to be seen -
| they're relatively new.
| epage wrote:
| My problem with docs in repos is it isn't as smooth to edit,
| especially if you have to wait for reviews.
| monocasa wrote:
| You can always just make the semantics of the doc folder or
| repo push permissions match what you're looking for, ie.
| 'no real reviews necessary to push to master' if that's the
| semantics you're looking for.
| NortySpock wrote:
| 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?
| FalconSensei wrote:
| > 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
| pkrotich wrote:
| We use self-hosted Readthedocs [0] with git/repo integration -
| merge to master triggers a build.
|
| [0] https://readthedocs.org/
| sneak wrote:
| Gitea supports web-based wikis that are git repos on the
| backend.
|
| It also has a good auth system and supports U2F (or SSO).
| sillysaurusx wrote:
| Notion.
___________________________________________________________________
(page generated 2021-10-02 23:00 UTC)