
Ask HN: When should my team start documenting? - cborenstein
When did you start writing documentation for your startup? How did you decide it was time to start? What were the first things you documented?
======
phendrenad2
When you do the same thing more than once ever, document it. So if in the
first minute that your startup exists you do something twice, document it.

Edit: I have to add this because I think I'll be misunderstood otherwise...
People tend to think of documentation as an all-or-nothing deal. Documentation
can be as simple as a README.md with "npm start" (or whatever the invocation
command for the app is) in it. Documentation doesn't need to have structure or
award-winning prose right off the bat. It doesn't need a table of contents or
a glossary. Just dump your thoughts on the project into a text file, and
refactor later.

~~~
d_jordan
Yeah, that's what I like to do as well. If it's something that I know I'm
going to do a few times, and I don't remember the process off the top of my
head the second time I'm doing it, write it down. I like to keep notes for
things I do day to day and revisit my notes at the end of the week to try and
find time to flesh them out a bit more and start organising.

~~~
cborenstein
very interesting. It seems like a good idea to not worry about the structure
when first writing things down but to reserve time at the end of the week to
organize. where do you usually write your "temp" notes? do you use any
structure or not until the end of the week?

~~~
d_jordan
I'll usually use something like oneNote, I find its folder structure really
handy for note editing because it kind of forces the user to organise as you
go. I'll try and make the note as detailed as I can as well because that'll
give more context about whether or not it's project specific, or more generic,
which makes it a little easier to classify at the end of the week.

------
cimmanom
Top priorities for documentation: how to set up a production environment; how
to get up a working copy running from scratch; any arcane command-line
incantations or click sequences that you have to look up (or worse, work out
by trial and error) more than twice. Document these from the get-go. In an
emergency you’ll be glad you have them, and the next person you onboard will
be grateful.

Second level priorities: complex algorithms; counterintuitive design
decisions; complex high-level business logic, especially logic that’s spread
across multiple methods/classes/modules. These are useful even for a solo
developer if you end up stepping away from that area of the code for more than
a month at a time. Once your team is big enough that people are regularly
editing parts of the codebase that someone else wrote (or that depend on code
someone else wrote) having this can save you hours of developer time per week.

Middling priority: documentation for HTTP APIs (and any other inter-process
communication APIs). If you can auto-generate as much of this as possible, do
so. I haven’t found it useful enough to put time into writing manually for a
team of <15, but this is also on the hours per week list if the people
consuming the APIs weren’t involved in writing or designing them.

Lowest priority: doc blocks and internal API documentation. Generally your
developers can work this stuff out on their own. Depending on your language,
API docs with function signatures may be auto-generatable, though the utility
is limited if your developers are already using IDEs and other tools that
provide autocomplete and lookups. Doc blocks with function descriptions are
useful if the function does something unintuitive or too complex to be
described in the name and should be written as part of general commenting
practice as a matter of course.

~~~
cborenstein
thanks for all of your suggestions. What do you find is the best way to
organize the command-line incantations (what a great way to describe them) and
click sequences? do you write them in something like google docs or confluence
or in your code?

~~~
cimmanom
Any of the above will work as long as everything’s well organized and easy to
find.

Personally I find Google Docs and Confluence impossible to locate stuff in.
Markdown docs within your main repository (or a central docs repository if for
some reason you have tons of repos, though IMO that’s an antipattern for a
small team) should work fine at least for a team or up to 20 or so.

------
s12345
I've found documentation on commands for running tests, running scripts, and
running other manual processes useful even if I've run the commands before
many times, and even if I was the one who created the commands. Documenting
anything you find yourself looking up a lot online, or in your Terminal
history would probably be useful even at the beginning just to reference for
myself.

As time goes on and the company grows, I think reasoning becomes useful to
document. Why were technical decisions made in code changes, why were tasks
deprioritized, why did tasks grow in scope or reduce in scope over time?

~~~
cborenstein
thanks for sharing - that makes sense. Where do you usually write your
runbooks? In a google docs/confluence type wiki or with your code? How do you
organize them so that you can find/share them quickly?

~~~
s12345
We write our runbooks in a wiki in Phabricator. We have a wiki per topic-- we
have one for getting started with the system that has some useful commands for
running tests, another for deploying the system, etc. I usually find them by
searching for terms that I remember are in them, but starting out, I was sent
some of the wiki pages.

------
ab_io
Ideally, from the get-go. Your system and documentation should be produced &
grow in-parallel. At worst, before any team members with key (undocumented)
domain knowledge leave.

