Ask HN: How do you document your applications?

#1

Post by mabn » Wed, Feb 22, 2017, 3:34 AM UTC

I'm wondering what are others using to store documentation of their (non-public) services. Github wiki looks nice, but including charts/diagrams is a pain. It has the advantage of keeping docs close to the code, but searching wikis does not work.

Confluence kind of works (and has gliffy integration!), but its search is also terrible.

I'm referring to documents like: architecture overview, what is it and how it works, user guide, but a place for javadoc/godoc would be nice as well.

What works best for you?

Re: Ask HN: How do you document your applications?

#2

Post by tjalfi » Wed, Feb 22, 2017, 4:25 AM UTC

I document my programs in .c format.

Re: Ask HN: How do you document your applications?

#3

Post by flukus » Wed, Feb 22, 2017, 4:49 AM UTC

I don't think you should need/want charts for developer documentation anyway. If you need charts to display the architecture for instance, but probably to focused on layering and not enough on producing code that actually does things.

The user guide can go on that shared drive where everyone ignores it anyway.

Re: Ask HN: How do you document your applications?

#4

Post by mabn » Wed, Feb 22, 2017, 8:57 AM UTC

flukus wrote: post #3

I don't think you should need/want charts for developer documentation anyway. If you need charts to display the architecture for instance, but probably to focused on layering and not enough on producing code that actually does things. The user guide can go on that shared drive where everyone ignores it anyway.

It's all cool until someone else has to touch this "code that actually does things".

Re: Ask HN: How do you document your applications?

#5

Post by flukus » Wed, Feb 22, 2017, 8:56 PM UTC

mabn wrote: post #4

flukus wrote: post #3

I don't think you should need/want charts for developer documentation anyway. If you need charts to display the architecture for instance, but probably to focused on layering and not enough on producing code that actually does things. The user guide can go on that shared drive where everyone ignores it anyway.

It's all cool until someone else has to touch this "code that actually does things".

And then it's still cool because they can see what it's doing instead of having the logic spread across 15 files in 6 layers.

Re: Ask HN: How do you document your applications?

#6

Post by [deleted] » Wed, Feb 22, 2017, 10:29 PM UTC

tjalfi wrote: post #2

I document my programs in .c format.

[deleted]

Re: Ask HN: How do you document your applications?

#7

Post by ceasos » Thu, Feb 23, 2017, 9:46 AM UTC

None of them is one best, but combined you can a make something that floats. I am also having similar situation, github wiki, issues, milestones, google docs, url to diagrams, readme... everything combined only gives what i strive for(so far). But still search, its PITA, I agree.