

Ask HN: How do you document you stack? - matth

I have a fairly large project and I want to make it as easy as possible for other developers who come on board to get a broad overview of the application's structure and behavior. Do you document your system in a single README.md file sitting in your app's root? Do you draw network topology maps? How do <i>you</i> go about documenting the intricacies and nuances of your program?<p>- Commenting code, obviously, helps a lot.
- bash scripts that document the build environment are awesome.
- A soft introduction in a README file.<p>Could I be doing thing smarter? Do you have any neat tools or processes you use?<p>Thanks.
======
JBerlinsky
I'm working on a rather large and (in my opinion) unwieldy C#-based project
right now that....well....tries. However, when your stack is at a point where
a Google Wiki isn't enough to document it adequately, there's an underlying
problem, namely that the people I'm working with have reinvented the wheel a
few times.

As a developer coming into a new environment/stack, there is nothing worse
than having to read through hundreds of pages to figure out how to run unit
tests. It's probably as bad, if not worse, than getting the "send an email to
___" treatment.

Keep your stack as simple as possible. New developers may not be experienced
with it, but we have this wonderful thing called Google. If you're using
common libraries, our Google-fu is strong. If you're reinventing the wheel,
you should probably reconsider your stack.

