Hacker News Reader

Comment by charezinski | Hacker News Reader

I worked with confluence, google docs and git like repos. Wholeheartedly prefer the last one.

It depends. An edit button with a WYSIWYG flow is much more conducive to casual fixes/updates than a fork -> clone -> edit -> build -> code review -> land workflow. But in-repo docs are easier to keep in sync with the code itself.

We like Git (alongside the code) for docs that are tightly coupled to the API, and Confluence / Google Docs for more general or high-level descriptions, design discussions, operational procedures, etc.

Git like repo? Could you please elaborate?

writing a lot of markdown docs. ;)

edit of a new page/section is a PR to the repo. once merged, you can auto deploy it to the target destination, rendering via jekyll or mkdocs or other things.

Discussions happen in PRs in that model. (you can also added previews of the PRs and deploy these next to the production version of the site)

the better your git repo tool supports online editting the better this experience will be.

Markdown type documents in a vcs are the best documentation system in my opinion. The problem really shows up when you are then trying to get non-technical users to participate, hence the abomination of wysiwyg web editors such as confluences (which is indeed broken, especially without plugins).

Markdown has lots of variants but is ok to wrangle most of time and pandoc handles it very well. Github renders it natively.

Emacs org mode is awesome and github renders it native but when not everyone is using emacs or a tool with org-mode plugins it it can cause issues when others try to access/edit it when using some of the more advanced features, so I use it for personal use and as a data science notebook. It replaces Jupyter notebook for me.

Asciidoc and Asciidoctor are currently the particular implimentation of markdown that is working towards a defined spec (https://asciidoctor.org/news/2019/01/07/asciidoc-spec-propos...) that I am leaning into the most. They are the best of both worlds. I am planning on moving my websites to asciidoc instead of org mode.

Documentation from code and code comments is much more specific and so I would say outside discussion scope.

I think that a markdown with a more well thought out spec such as asciidoc(tor) are working towards is going to be the future, and I think that the wysiwyg tools themselves are the main pain point and are what need to be worked on the most.

In the past when I have had to deal with confluence I have just asked confluence admins if we can use the github or html frames plugins so I can do documentation independent of confluence itself.

Reply on news.ycombinator.com