TE
科技回声
首页24小时热榜最新最佳问答展示工作
GitHubTwitter
首页

科技回声

基于 Next.js 构建的科技新闻平台,提供全球科技新闻和讨论内容。

GitHubTwitter

首页

首页最新最佳问答展示工作

资源链接

HackerNews API原版 HackerNewsNext.js

© 2025 科技回声. 版权所有。

Ask HN: When should my team start documenting?

10 点作者 cborenstein超过 6 年前
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?

4 条评论

phendrenad2超过 6 年前
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.<p>Edit: I have to add this because I think I&#x27;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 &quot;npm start&quot; (or whatever the invocation command for the app is) in it. Documentation doesn&#x27;t need to have structure or award-winning prose right off the bat. It doesn&#x27;t need a table of contents or a glossary. Just dump your thoughts on the project into a text file, and refactor later.
评论 #18556256 未加载
评论 #18555126 未加载
cimmanom超过 6 年前
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.<p>Second level priorities: complex algorithms; counterintuitive design decisions; complex high-level business logic, especially logic that’s spread across multiple methods&#x2F;classes&#x2F;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.<p>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 &lt;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.<p>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.
评论 #18556381 未加载
s12345超过 6 年前
I&#x27;ve found documentation on commands for running tests, running scripts, and running other manual processes useful even if I&#x27;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.<p>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?
评论 #18556411 未加载
ab_io超过 6 年前
Ideally, from the get-go. Your system and documentation should be produced &amp; grow in-parallel. At worst, before any team members with key (undocumented) domain knowledge leave.