[ken]

I actually like writing documentation, even if I'm not great at it yet, but I struggle to be able to do this well for other people's software. I feel that project documentation, to be done well, has to be part of the project itself.

Half the time I start writing documentation for a feature I've built myself, I go back and rework the design based on what I learned from trying to document it. It's rather enlightening to write "Here's how to do this thing that you'll do 100 times a day...", and then discover to your horror that it takes 14 steps. Oops.

And when you try to document the why and how of most open-source projects, it very often comes down to "historical accident" and "it's like some other ancient system you've probably never used either". There's a lot of features where I'd just write "This next dialog box is useless, so just hit return", or "This thing you have to type is completely nuts, so just memorize this nonsense".

I believe that's why third-party documentation (O'Reilly books, The Missing Manual series, etc) is so successful. It's a lot easier to write (tactfully) "This is dumb, so here's how you get past it", than to go back and fix the feature. And nobody wants to write documentation about their own software that says "Yeah, I know this thing you have to do here is dumb, but hey, it's only a 1.0 so please don't hurt me."

[kakwa_]

On my personal projects, I like writing the documentation.

What I specially like is having the documentation live right next to the software, typically in the same repository. That way, you have a clear incentive to update it when doing change in the code, and it's also clearly versioned with the software (1000 thanks to read the doc), you can also treat gap in the documentation as bugs.

However, writing good documentation can be really hard. As the developer, you are, at the same time, the best and worst placed person to document. Best because you know exactly how the software is supposed to work, and worst, because you might miss documenting things that seems obvious to you, but not to the user.

Lastly, as a developer, it can be hard to take a step back, and give a higher level view of the documentation, not diving directly into too much details.

For that, having reviewing from an external eye, and feedback from users can be really helpful.

[Hamatti]

> However, writing good documentation can be really hard. As the developer, you are, at the same time, the best and worst placed person to document. Best because you know exactly how the software is supposed to work, and worst, because you might miss documenting things that seems obvious to you, but not to the user.

This is an important point! That's why I think it's so valuable to constantly have discussions with the users of your products. Not only to improve the products themselves but the documentation and the on-boarding process.

[felicianotech]

I really like your point about third party documentation. I've written the "this is dumb" line before but that's usually on a forum not a doc.

[Hamatti]

I totally agree with you. It requires good understanding of the project but also it's beneficial to know the pitfalls and decisions made or left unmade that ended up shaping the project. That's why I encourage developers to make documenting (just like testing) a part of feature development and bug fixing rather than an additional hurdle.

I like Tom Preston-Werner's Readme Driven Development[0] approach. Instead of leaving documentation as something that happens as an afterthought, start with it. I've tried it a few times with my smaller hobby projects and it has helped me a lot.

Similar to TDD, RDD allows me to design the API before I ever write the actual code. I also get to design the build process, contribution model and bunch of other things up front.

When it comes to the "why" of projects, I like DHH's Doctrine document[1] on Ruby on Rails. I wish more software projects would feature a similar document since that answers a lot of questions, especially about the opinionated decisions.

[0] http://tom.preston-werner.com/2010/08/23/readme-driven-devel... [1] https://rubyonrails.org/doctrine/