1 pointby hahnbee2 hours ago3 comments
  • necovekan hour ago
    I generally liked Python doctests: runnable documentation. It is really an amazing concept, only a step removed from literate programming IMO.

    Two problems with it were that 1. often setup boilerplate overshadowed the actual essence of the documentation and 2. people abused them for e2e testing making for unreasonable reading (and slow testsuite runs).

  • verdverm2 hours ago
    git + markdown is the way, especially in these agentic days

    plenty of tools to turn that into html if you want

    confluence is bloated an unweildy

    Jira done well is actually nice

    • necovekan hour ago
      Has anyone seen Jira done well? And no matter how it's done, it is always slow and bloated.

      Confluence is slow but pretty simple, standard wiki otherwise. Obviously, if I had a choice, it'd be nothing Atlassian.

      git+markdown limits editing to developers only.

      • verdverman hour ago
        Jira has improved massively the last 2-3 years, it's faster than GitHub now in my experience

        The question was about developer documentation, so non-developers was put to the side in my answer. We are also now in the agentic age, so git + markdown is operationally much more aligned with the primary doc producer and consumer. We are more managers and editors these days.

        • necovekan hour ago
          I have not seen the improvement in Jira: if anything, it only feels slower.

          GitHub Issues today seem bloated too, so perhaps your frame of reference has moved backwards while you weren't looking and suddenly Jira is fast?

          • verdverman hour ago
            I use Jira daily for ~8 years, it has become faster in it's own comparison over time.

            Jira is a highly customizable beast, it does matter how your Jira wizard sets things up

  • davidmartin_tgaan hour ago
    [flagged]