Hacker News Reader

Comment by bsdpufferfish | Hacker News Reader

I can't imagine working on large document in WYSWIG opaque formats anymore. Plain text file formats with version control is the only scalable toolset that won't lose your work.

View on HN

Markdown-in-git used to be used for tech specs at my company. Now we switched to Google Docs, which means we need to maintain a "change log" section at the bottom because Docs history is... not a commit log.

Markdown in git, reviewed as a pull request on GitHub, is the best way to do an RFC. I will die on this hill.

Alternatively, I wonder if an old school message board would work. Each RFC gets its own (sub)board, and within that board each thread is a discussion about some topic -- an individual review, debate about a section, etc. I wonder if such a thing already exists, _specifically_ for technical specification review.

> Markdown-in-git used to be used for tech specs at my company. Now we switched to Google Docs

I'm so sorry. Any rueful ideas on how another company might avoid that pitfall?

Not sure how to avoid. I think it was two things:

1. Some devs just didn't like having review discussions as PR comments. Maybe it's the way that the threads break up the markdown source. Or maybe WYSIWYG feels better for doc review. I also recall people saying "it's hard to know what's changed, could you add a changelog section?" When I replied "it's a git repo, and I leave detailed commit messages," there was no response. I think this means that they don't like that.

2. The managers who decide things don't use git. We use Google Docs for everything else, why not for this?

In the end, Google Docs works well enough. I do miss the commit log, though. It's tricky to link to a previous revision in the changelog table -- maybe I'll get into the habit of it.

Both GitHub PRs and Google Docs have this problem, though: There's no ready record of the review process -- the comments. They eventually disappear and are difficult or impossible to retrieve, and they lose context.

Not like anybody is bothering to dig.

> There's no ready record of the review process -- the comments. They eventually disappear

I wonder if someone could build something clever with git-notes [0] to capture such discussions in the repo itself.

I'm sure others have thought about it already, so there must be some kind of pitfall... A little more searching finds projects like git-appraise. [1]

[0] https://git-scm.com/docs/git-notes

[1] https://github.com/google/git-appraise

What about a wiki, like xwiki or others ? They have diff for changes (changelo), comments and in inline @user prompts.

> I wonder if an old school message board would work.

It's called Redmine.

Eg: https://redmine.pfsense.org/issues/14139

Trac is still around, too. 1.6 came out a few months ago.

Confluence does a great work of having a WYSWIG editor and keeping a log of changes on a document.

And there are no file formats that support it, unless you go to something like Markdown.

LaTeX seems like it fits the bill.

I have used LaTeX for a lot of things and it is a pain to use. It is like everything is stuck in 70s, from the syntax to the toolchain to package management.

I don't use LaTeX for anything these days but Typst popped up recently and seems like a decent alternative: https://github.com/typst/typst

I dont like the idea of embedding a scripting language in my documents at all.

I mean LaTeX is Turing complete as well. It is just that scripting is very clunky to use.

Well, sure, I think thats part of the problem with it.

I dont think either of them have to be turing complete though.

Have a look at Typst then. It's a fresh take on the concept.

Otoh I feel like it forces me to keep it simple. I have two or three templates I've been using for decades, occasionally needing an update because some package was deprecated. Documents are not like Web Design where every two years someone comes up with completely new design guidelines based on the latest super duper awesome user testing and UX research and everything we did before was inferior.

To be fair, printed documents used to be like that for the first one or two centuries of their existence.

Another way of looking at it is that LaTeX is so good no one has managed to come up with something better.

I recently started using it because Lyx does not work on my ARM based Linux tablet and its not too bad when used with a GUI editor.

It is a lot more powerful than other things I use (Markdown, Sphinx) and a lot better for version tracking and multiple output formats than word processors.

You could also use docbook. My gut feeling is, that if you have large documents that you collaboratively work on, there's probably a bit of a compilation process to be done and other stuff you want to do with the document.

So the overhead of semantic markup of the whole content (instead of just marking words as bold) might be worth it.

Typically the big task of a large document is focused on content and organization, and the formatting is a separate concern.

XML is a good start to describing structured text.

Well, it depends.

If you're compiling a report for a college group project (or the workplace equivalent of that) you might well need things like equations and tables and suchlike.

For example if you've got a table of performance results with the best performer in each row highlighted in bold, a fact the text references - then separating content and formatting doesn't really make that much sense.

Just an example. Obviously the more formatting control you need the fancier your language and tool is. Tex is the upper bound.

> For example if you've got a table of performance results with the best performer in each row highlighted in bold, a fact the text references - then separating content and formatting doesn't really make that much sense.

You can tag the text as "important": see <strong> vs. <b> in HTML.

Reply on news.ycombinator.com