3 ms·

> anything they ask, tell them it’s now their role to document it. Depending on how you interpret it, this advice is either great or terrible. If you read this

> anything they ask, tell them it’s now their role to document it. Depending on how you interpret it, this advice is either great or terrible. If you read this to mean that the new person to a project should start out by documenting the things they don't know, then this is bad: - There are definitely Open Source projects which have this attitude and don't write user-facing documentation, expecting new-joiners to write it. This makes it both hard for a new person to join a project and hard for the project to market itself. - If you are just starting out on a project, it can be hard to know what are the key concepts that a person should really know in order to be efficient and what is incidental. It may or may not be a good idea for them to spend a bunch of time documenting ways in which your test setup uses selenium after running into some really weird end-to-end test bug. - If you don't know something, it is really hard to write a coherent explanation of it. You have to both empathize with ignorance and have the knowledge. Otherwise, you can just end up stuck/lost. If you don't have anyone willing to help you un-stick yourself... But that doesn't sound like the interpretation you mean. From the rest of your post, it very much sounds like you mean that the new person should turn a vocal explanation into a written one as a way of both confirming their knowledge and passing it on to others. This sounds great. It will generate lots of draft docs though, so you probably need some habit or person to keep them organized and keep them from getting stale.

bertil 9y ago
I certainly try to structure their documents a lot, and point them at the people who can answer their question -- although most of my energy is spent not assaulting anyone refusing to document properly with ”but I know it, so it's fine, you just have to ask me” or ”but it’s on an email somewhere, is that not enough?”. The best audience for the document is “who you were two days ago” and they generally have some empathy for that person for a day or two.

bertil 9y ago

I certainly try to structure their documents a lot, and point them at the people who can answer their question -- although most of my energy is spent not assaulting anyone refusing to document properly with ”but I know it, so it's fine, you just have to ask me” or ”but it’s on an email somewhere, is that not enough?”. The best audience for the document is “who you were two days ago” and they generally have some empathy for that person for a day or two.