Hacker News Reader

Comment by rapnie | Hacker News Reader

The observation that hardcore True Developers™ absolutely hate documentation chores is maybe reflected in low upvote and comment count on this thread.

But seriously, this is a good listing of pros and cons, and it is a pity not more experiences are shared. Commercial products usually pay good attention to the docs, but esp. FOSS projects are often severely under-documented. Model may be different here as often the single dev is the documenter too (and hates that chore). I tried Readme Driven Development [0] for a while, but found it still resource-intensive to keep things up-to-date. For single devs, small teams the Diátaxis framework [1] is helpful to organize and makes the task a bit lighter.

[0] https://tom.preston-werner.com/2010/08/23/readme-driven-deve...

[1] https://diataxis.fr/

View on HN

I started doing documentation driven development a while back (with FOSS code) I wrote and I realized at some point that my tests and my how to docs were doing the same thing - one was just an easier to read version of the other.

Moreover, when one went out of date so did the other.

So, I tied them together - I wrote integration tests such that with a jinja2 template I could autogenerate readable markdown how-to docs from the tests and their artefacts.

Setting that up led me to the realization that writing docs isn't actually tedious at all. It's the writing things down 3 times (spec, test & docs) and keeping them in sync that is tedious. And that part can be automated.

If there is a framework to build the whole bundle of docs from integration tests, integration test metadata, integration test artefacts, schemas, code and an assortment of high level explanatory texts then it stops being a chore. It actually becomes fun.

It means that DDD becomes integration TDD. The only difference is that I will write an additional 3-4 explanatory sentences alongside the integration test I write before the feature and run a "docgen" script afterwards.

What are your thoughts on BDD and Gherkin test scripts? The federated Diaspora* app has a BDD test suite [0], and for the Fediverse people are test-driving if it is applicable for ActivityPub compliance testing [1].

[0] https://github.com/diaspora/diaspora/tree/develop/features

[1] https://codeberg.org/helge/fediverse-features

I don't like gherkin. I think that it has awkward syntax, it lacks type safety, it's very verbose and doesn't have enough ability to abstract scenarios. Rather than being a source for generating the documentation it tries to be the documentation.

Nonetheless, there is a small number of projects where they either work around these constraints or it doesn't matter as much, so it can work. I find that most people that apply gherkin to their projects run into a brick wall though - usually for one of the above reasons.

I built https://github.com/hitchdev/hitchstory as an alternative that has straightforward syntax (YAML), very strict type safety (StrictYAML), low verbosity and the ability to abstract scenarios.

It is explicitly designed as a source for generating markdown documentation so that you can create richer docs like https://github.com/hitchdev/hitchstory/blob/master/examples/... for your users rather than more test-like documents like https://github.com/diaspora/diaspora/blob/develop/features/m...

Nice. I like the approach, thank you.

Documentation is such a broad area I think it's big enough for everyone to hate something.

There's

- how (implementation, how the system works)

- what (what the system is for, it's purpose

- why (design)

And there's audiences

- developers (using the interfaces)

- architects (designing the interfaces)

- testers (validating the interfaces)

- operators (running the system)

- managers (organizing development efforts)

And at some companies it's 1 person doing all of that. I think once you start to add more people, you start to have debates about documentation. The programmer might have written "clean" code and automated tests which are understandable to other programmers but less useful to project managers and operators.

Everyone wants good documentation, no one wants to pay for a technical writer.

"I mean c'mon, how difficult can it be to write technically ?"

Reply on news.ycombinator.com