7 ms·

Why would you need a tool like this if you’re writing markdown docs outside the browser and version controlling them with Git? Doesn’t that defeat the entire pu

• zelphirkalt 2y ago
  > Or is it just you want a developer-native workflow to upload docs intended for the rest of the non-developer team? This. I am so annoyed by all the quirks and silly dysfunctional behavior of confluence, when all I need is a developer friendly workflow, that actually motivates to keep documents up to date and allows diffing easily and quickly and blaming and all that good stuff you get when you have git or other capable vcs. > In general, I would say that's a really bad idea. If you’re dumping this self-hosted (and probably bug filled MVP, as all are) on your team, yet never having to deal with the UI layer that everyone else does…it’s a recipe for revolt and tool churn. I don't see how. Users of the UI could, without explicitly knowing, save pages creating commits themselves. Maybe it could be difficult to square that with collaboratively working on a document in realtime though. If I had to choose between the two, I would pick git workflows any day of the week though and it is not so often the case in my experience, that people really work collaboratively on wiki pages of documentation. > I’ve seen this mistake a million times from technical founders. Same thing will happen with your marketing website CMS, after you realize static site + markdown + git doesn’t scale to non-dev humans and the headless CMS you picked (but never interact with) is actually trash in daily use. That is, why I am suggesting my points as additional, not as replacement. The non-devs can have their clicky bunty UI, but please let me use efficient workflows as a developer and don't create a sluggish experience in the browser, that will never motivate any dev to maintain documentation inside of it. Also markdown does not do the job. It does not have some of the necessary building blocks. It is good for simple pages and perhaps a readme, but when it gets to proper technical documents, I would rather have something more capable. For example restructuredText, where you can define custom directives and so on. I used that before to make a little wiki with document interlinking functionality when rendering and used it to write a thesis. It is very capable. But there are others like org-mode format, and asciidoc and more. All more capable than standard markdown. (And yet, confluence has already issues with standard markdown, lol.) An alternative is, of course, not to force devs to use confluence for documentation. Keep confluence to the marketting and sales fluff, and let engineers use efficient tooling, that they are already familiar with and that accompanies the code, instead of dividing documentation out into confluence, where it will quickly become unmaintained and forgotten.
  • inhumantsar 2y ago
    man I have a hard enough time coaching new grads and juniors through borked rebases and merges, I would do anything to not be the one trying to automate that for HR and accounting people using what looks to them like any other word processor.
  • clcaev 2y ago
    As the parent post observes, I've also yet to see a GUI that works with Markdown and static site generators. This doesn't mean it's a bad idea. It has to be good enough to dogfood. It'd be nice to implement the non-technical workflow as producing a pull request via a branch. Each save (even autosave after N minutes) could be its own commit. The user could see their changes from their branch in near realtime. Markdown isn't an issue, it's a benefit, although explicit support for images and diagrams is needed. The GUI workflow could see if an automatic merge works, if not, it is fine to require manual intervention. Another option is to swap branches, copy main branch, rollback main branch to the place before any conflicts emerged, and then apply changes. Bonus points for using CRDT for handling multiple users working together on a page during a conference call on the same branch.