logoalt Hacker News

rkangelyesterday at 10:15 PM0 repliesview on HN

I and my team did a full set of documentation for handing over a codebase to the client. A large complex codebase with accumulated history and subtle reasons why things were done.

Diataxis was fantastic. It took a bit of effort to work out what the page titles were to cover everything we needed, but then when you were writing a page it was glorious.

It was so clear what you were saying and what "voice" you were writing in. If it's a Reference page you're all descriptive, with diagrams and bullet points. When it's a guide you're more discursive, but you know you're just imparting information not trying to teach. It made it so much easier to be coherent and clear about everything.