5 ms·

1. Working in pairs or teams. Avoid solo people working on projects. 2. Common, easily searchable place to put all documentation at. Good search capability is

1. Working in pairs or teams. Avoid solo people working on projects. 2. Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok. 3. A good code & commit search engine. Ability to search code reliably obviates the need for a lot of documentation. 4. Weekly knowledge sharing sessions with the whole team. Both presenters and question askers need to be rewarded to keep engagement. It is like replication in distributed systems. There are varying levels of redundancy you can get, and each higher levels involves higher overhead than the previous, so there is no golden rule - it needs to evolve as the organization evolves. A startup might have many people who are the only people who know certain things, but a 10000-person company surely should not have any institutional knowledge bound to one person.

dehrmann 7y ago
> Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok. I have mixed feelings around documentation because I can often read the code faster than the docs, and docs are often incomplete, inaccurate, and out-of-date. Docs for truly long-lived things are nice, though. As for good search, that's easier said than done. The heuristics Google used for search don't work in code, and searches are too rare to do useful ML for relevancy. Edit: seeing the downvotes... I don't actually mind writing documentation, but more often than not, I've found people like(?) writing it because it makes them feel like they're improving the situation by doing something. I'd rather the effort be spent on better naming and factoring in code. Docs are also very prone to rot and drift. That said, I've found Java docs, MDN, and most man pages to be very good, in part because of how thought-out the docs are and how static the interface is. I'm also a fan of docs that bootstrap new developers. Someone else said they like docs describing "principles," and I like that idea--guidance so you know what A should do vs. what B should do.
- mandelbrotwurst 7y ago
  Your position is reasonable. The value of spending time on documentation in a vaguely specified and frantically written web app is not the same as, e.g. writing documentation for the frameworks that drive that same application.
  - asdff 7y ago
    Even with the most frantic half effort of a project, its helpful to give the context of why you are doing it, why you approached the project this way, and why you ended up not going with another approach. Maybe you did try what should have been the best approach at first, and it didn't work right, so you had to do something not as good but good enough. Then in the future someone decides to try to redo what you've done using the best approach, and they hit a wall because you never wrote down that you tried that and it didn't work for x reason. Writing up what you do helps keep your own thought process organized, so it's beneficial for you even if you never read what you wrote.
    - mandelbrotwurst 7y ago
      Definitely!
- raz32dust 7y ago
  I didn't mean documentation at the code level - I believe well-written code is always better than docs - it should not be used to hide badly written code. I was talking about documentation like product requirements, meeting notes, decisionf and trade-offs, design etc.
- ascar 7y ago
  > I have mixed feelings around documentation because I can often read the code faster than the docs, and docs are often incomplete, inaccurate, and out-of-date. The problem I have everytime time I read or hear this statement, is that code is excellent in telling "what" happens, but often very opaque in "why" it's done like that. If the why isn't clear, code might be changed/refactored and stuff breaks, because the developer didn't understand the reasons behind the apparent code smell. It's comparable to Chesterton's Fence [1]. I much rather have some additional documentation than "self-documenting code" that does (apparently) weird things and tells me nothing about the reasons. Also outdated documentation can be helpful, when it's version controlled. That gives you context how the code evolved and if it doesn't state it directly at least pointers why the code is like it is now. That's also why I mostly prefer in code documentation to Confluence/wiki documentation, because the time/change relationship between code and wiki is much harder to comprehend. [1] https://en.m.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fence https://en.m.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fen...
- larsrc 7y ago
  The problem with "Read the source, Luke" is that even if the code is well written (and that's a big if), reading the code only tells you _what_ it does, not why, not why it doesn't do it differently, nor what it may or may not do in the future. It's the difference between programming and software engineering.
- teddyuk 7y ago
  The way I like to think about a well documented system is: - unit tests show how well the developer understood the requirements at the time they wrote the code - git commit history shows who and when something changed (probably assuming history not rewritten :) ) - git history can be more informative, if and it is a big if, the developers write enough information and not just “changed code” type comments - in-line comments are for “why” - explaining things that look odd or go against standards or best practices, or “I’m doing this now like this, when x is available use that” - notes to help you and others - wiki is for higher level “why” to help people understand the code, where there is a lot of complexity I really like the idea of a “book of the xx” like the book of the runtime here: https://www.hanselman.com/blog/TheBookOfTheRuntimeTheInternalsOfTheNETRuntimeThatYouWontFindInTheDocumentation.aspx https://www.hanselman.com/blog/TheBookOfTheRuntimeTheInterna...
- jskrablin 7y ago
  While reading 'teh codez' can work for a (simple) app it will get you nowhere regarding the whole service architecture/infrastructure. There can and will be several services/apps working together, external services required for some stuff, different set of configurations for different environments, CI/CD, software packaging, etc... How we deal with it where I work - service developers/owners are responsible for providing docs for their services. Ops provide infra/CI/deployment/high level 'how all this works together' docs. Everything that can be code, should be code - with it's documentation. Of course there's issue tracker, wiki, commit messages all tied together using issue tracker IDs, etc. And it still takes time for new people to get their heads around the 'how everything is working together'. Amount of docs we're writing is significant. Some of the docs is auto generated. Time for docs keeping is accounted for at estimating the time required for developing new features. Being a member of a remote team I can't imagine how we could be able to work otherwise.
mitko 7y ago
Re: easy search. Slapdash can handle search in all your work wikis/docs at once and is very fast. It can search github/gitlab too. I am part of the team there.
- fancyfish 7y ago
  Thank you. I find Slapdash a great way to navigate our wikis by app, incorporating Google Docs, GitHub repos and other resources. By lowering the friction to making and using good docs, our docs have improved by a wide margin. The search is lightning fast and I can do most things via keyboard shortcut. Pricing is cheap too!
Techies4Trump 7y ago
Solo people working on projects aren't too bad so long as they communicate the work they're doing and document it well. Some people just work better on their own. IMO, what's worse are "knowledge hoarders". Usually they've been in the company for a long time and they maintain their position by being as stingy as possible with their knowledge. You usually find these people in big orgs, and they can be quite toxic. They also don't write good documentation.
- Drdrdrq 7y ago
  > Solo people working on projects aren't too bad so long as they communicate the work they're doing and document it well. Strongly disagree, been there, hurt like hell. Solo people on projects mean that other people can't give meaningful reviews (because they don't know the project that well, and because they have their own work), leading to 1. developer not getting good feedback and improving, 2. higher risk of them going down some rabbit holes, 3. bus factor of one and stressful vacations, 4. less guarantee that the docs and the code are any good, 5. a danger that this solo developer will turn into one of those "knowledge hoarders". Solo development is never OK (imnsho). Sometimes you can't avoid it, but it should be a calculated risk, and only a temporary one.
  - tatar 7y ago
    I've found your comment compelling. I'm assuming you have some unit economics implied here, I'm very curious to learn from your experience. What would you say, in a team of 6 devs, if a pm just walked up and said "If we can get 6 different tasks done in a week versus 3, guess which one I'm gonna pick?"
  - raxxorrax 7y ago
    In my experience it can work quite well. I work alone on many projects. Given, you need support staff. I have someone to document everything aside from the most technical parts that I need to write myself. Also a project manager that extracts requirements and expectations from customers. Doing that myself would increase project duration tremendously. It is pretty common in the embedded world in smaller companies. There just aren't enough developers to render enough support. The problem with one-man-shows is the dependability. A lot of web developers go that route. But if they are unavailable because of private stuff or illness, the project they are working on is basically iced.

dehrmann 7y ago

> Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok. I have mixed feelings around documentation because I can often read the code faster than the docs, and docs are often incomplete, inaccurate, and out-of-date. Docs for truly long-lived things are nice, though. As for good search, that's easier said than done. The heuristics Google used for search don't work in code, and searches are too rare to do useful ML for relevancy. Edit: seeing the downvotes... I don't actually mind writing documentation, but more often than not, I've found people like(?) writing it because it makes them feel like they're improving the situation by doing something. I'd rather the effort be spent on better naming and factoring in code. Docs are also very prone to rot and drift. That said, I've found Java docs, MDN, and most man pages to be very good, in part because of how thought-out the docs are and how static the interface is. I'm also a fan of docs that bootstrap new developers. Someone else said they like docs describing "principles," and I like that idea--guidance so you know what A should do vs. what B should do.

mandelbrotwurst 7y ago
Your position is reasonable. The value of spending time on documentation in a vaguely specified and frantically written web app is not the same as, e.g. writing documentation for the frameworks that drive that same application.
- asdff 7y ago
  Even with the most frantic half effort of a project, its helpful to give the context of why you are doing it, why you approached the project this way, and why you ended up not going with another approach. Maybe you did try what should have been the best approach at first, and it didn't work right, so you had to do something not as good but good enough. Then in the future someone decides to try to redo what you've done using the best approach, and they hit a wall because you never wrote down that you tried that and it didn't work for x reason. Writing up what you do helps keep your own thought process organized, so it's beneficial for you even if you never read what you wrote.
  - mandelbrotwurst 7y ago
    Definitely!
raz32dust 7y ago
I didn't mean documentation at the code level - I believe well-written code is always better than docs - it should not be used to hide badly written code. I was talking about documentation like product requirements, meeting notes, decisionf and trade-offs, design etc.
ascar 7y ago
> I have mixed feelings around documentation because I can often read the code faster than the docs, and docs are often incomplete, inaccurate, and out-of-date. The problem I have everytime time I read or hear this statement, is that code is excellent in telling "what" happens, but often very opaque in "why" it's done like that. If the why isn't clear, code might be changed/refactored and stuff breaks, because the developer didn't understand the reasons behind the apparent code smell. It's comparable to Chesterton's Fence [1]. I much rather have some additional documentation than "self-documenting code" that does (apparently) weird things and tells me nothing about the reasons. Also outdated documentation can be helpful, when it's version controlled. That gives you context how the code evolved and if it doesn't state it directly at least pointers why the code is like it is now. That's also why I mostly prefer in code documentation to Confluence/wiki documentation, because the time/change relationship between code and wiki is much harder to comprehend. [1] https://en.m.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fence https://en.m.wikipedia.org/wiki/Wikipedia:Chesterton%27s_fen...
larsrc 7y ago
The problem with "Read the source, Luke" is that even if the code is well written (and that's a big if), reading the code only tells you _what_ it does, not why, not why it doesn't do it differently, nor what it may or may not do in the future. It's the difference between programming and software engineering.
teddyuk 7y ago
The way I like to think about a well documented system is: - unit tests show how well the developer understood the requirements at the time they wrote the code - git commit history shows who and when something changed (probably assuming history not rewritten :) ) - git history can be more informative, if and it is a big if, the developers write enough information and not just “changed code” type comments - in-line comments are for “why” - explaining things that look odd or go against standards or best practices, or “I’m doing this now like this, when x is available use that” - notes to help you and others - wiki is for higher level “why” to help people understand the code, where there is a lot of complexity I really like the idea of a “book of the xx” like the book of the runtime here: https://www.hanselman.com/blog/TheBookOfTheRuntimeTheInternalsOfTheNETRuntimeThatYouWontFindInTheDocumentation.aspx https://www.hanselman.com/blog/TheBookOfTheRuntimeTheInterna...
jskrablin 7y ago
While reading 'teh codez' can work for a (simple) app it will get you nowhere regarding the whole service architecture/infrastructure. There can and will be several services/apps working together, external services required for some stuff, different set of configurations for different environments, CI/CD, software packaging, etc... How we deal with it where I work - service developers/owners are responsible for providing docs for their services. Ops provide infra/CI/deployment/high level 'how all this works together' docs. Everything that can be code, should be code - with it's documentation. Of course there's issue tracker, wiki, commit messages all tied together using issue tracker IDs, etc. And it still takes time for new people to get their heads around the 'how everything is working together'. Amount of docs we're writing is significant. Some of the docs is auto generated. Time for docs keeping is accounted for at estimating the time required for developing new features. Being a member of a remote team I can't imagine how we could be able to work otherwise.

mitko 7y ago

Re: easy search. Slapdash can handle search in all your work wikis/docs at once and is very fast. It can search github/gitlab too. I am part of the team there.

fancyfish 7y ago
Thank you. I find Slapdash a great way to navigate our wikis by app, incorporating Google Docs, GitHub repos and other resources. By lowering the friction to making and using good docs, our docs have improved by a wide margin. The search is lightning fast and I can do most things via keyboard shortcut. Pricing is cheap too!

Techies4Trump 7y ago

Solo people working on projects aren't too bad so long as they communicate the work they're doing and document it well. Some people just work better on their own. IMO, what's worse are "knowledge hoarders". Usually they've been in the company for a long time and they maintain their position by being as stingy as possible with their knowledge. You usually find these people in big orgs, and they can be quite toxic. They also don't write good documentation.

Drdrdrq 7y ago
> Solo people working on projects aren't too bad so long as they communicate the work they're doing and document it well. Strongly disagree, been there, hurt like hell. Solo people on projects mean that other people can't give meaningful reviews (because they don't know the project that well, and because they have their own work), leading to 1. developer not getting good feedback and improving, 2. higher risk of them going down some rabbit holes, 3. bus factor of one and stressful vacations, 4. less guarantee that the docs and the code are any good, 5. a danger that this solo developer will turn into one of those "knowledge hoarders". Solo development is never OK (imnsho). Sometimes you can't avoid it, but it should be a calculated risk, and only a temporary one.
- tatar 7y ago
  I've found your comment compelling. I'm assuming you have some unit economics implied here, I'm very curious to learn from your experience. What would you say, in a team of 6 devs, if a pm just walked up and said "If we can get 6 different tasks done in a week versus 3, guess which one I'm gonna pick?"
- raxxorrax 7y ago
  In my experience it can work quite well. I work alone on many projects. Given, you need support staff. I have someone to document everything aside from the most technical parts that I need to write myself. Also a project manager that extracts requirements and expectations from customers. Doing that myself would increase project duration tremendously. It is pretty common in the embedded world in smaller companies. There just aren't enough developers to render enough support. The problem with one-man-shows is the dependability. A lot of web developers go that route. But if they are unavailable because of private stuff or illness, the project they are working on is basically iced.