Ask HN: How do you document you stack?

3 pointsby matth15년 전1 comments

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 you go about documenting the intricacies and nuances of your program?

- Commenting code, obviously, helps a lot. - bash scripts that document the build environment are awesome. - A soft introduction in a README file.

Could I be doing thing smarter? Do you have any neat tools or processes you use?

Thanks.

1 comments

JBerlinsky15년 전

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.