5 ms·

> Documentation is everything What I learned after managing a small team for 2 years is that documentation is only good if the team can find it, if the team bo

> Documentation is everything What I learned after managing a small team for 2 years is that documentation is only good if the team can find it, if the team bothers to look for it, and if the team takes the time to read it. I can't tell you how many times I've linked pertinent documentation in Confluence from the Jira task, only to have the developer ignore it. What black magic do you have to cast to get devs to look at the documentation?

gumballindie 3y ago
> What black magic do you have to cast to get devs to look at the documentation? README.md files in each repo, and code level documentation. The readme file can point to useful links, such as diagrams or stuffy documents where needed.
- ozim 3y ago
  You don't put everything in README.md for the start - once file gets long enough no one will read it the same as bunch of confluence... Links? Parent poster just mentioned he was putting relevant links in JIRA tickets - to work on a feature dev has to open the ticket anyway but suprise-suprise they were not clicking the links. How on earth README.md links will help in such situation.
  - gumballindie 3y ago
    Oh when i read documentation i think stuff relevant to getting things to run, architecture and perhaps a little more of whats relevant. Jira tickets and all can be correlated with a proper branching model. I agree, readme files should be concise.
stock_toaster 3y ago
> What black magic do you have to cast to get devs to look at the documentation? Not use Jira and Confluence? More seriously, I have found that confluence is where documentation goes to die. Something about the tooling, the slowness, poor search, admin tools leading to overzealous compartmentalization, not-quite-good plain text format, awkward gui editing tools, versioning system, distance from the code[1]... something... just makes it not really great at being a repository for keeping documentation up to date, or easily usable. [1]: eg. not using the same tools/editors to modify the documentation as you do the code
- sodapopcan 3y ago
  Ya, there is some wisdom in "don't use Confluence". It's far too heavy for a wiki. Maybe it's fixed by now why should a plain text page show a loading spinner?? I'm personally a fan of one massive README with a table of contents for technical docs. YMMV. Also, definitely link the docs in the description and not the comments. I've found that you should never rely on anyone reading the comments (or re-reading them, at least). Any important info that is surfaced in comments should be moved to the description. Of course, if you're team isn't going to read tickets then that's just a plain problem.
- paulddraper 3y ago
  There is truth to this. Notion, etc are far more pleasant, readable, and lend for better organization.
- smcleod 3y ago
  Yeah confluence and jira both need to go away, both of them make it very hard to find information and feel like such a burden to use.
TylerE 3y ago
Not stuffing it into some horrible slow "enterprise" webapp would be a start.
- ozim 3y ago
  Are we using the same Confluence and JIRA - I don't see it being slow as we use cloud. Only times when it was slow it was long time ago when it was on premise and business always skipped upgrading any servers so admins had to run it on tight rope.
  - lmm 3y ago
    > Are we using the same Confluence and JIRA - I don't see it being slow as we use cloud. Well no we're not - if you're using "cloud" then you get randomly assigned an instance, some of them are fast and some of them are slow (presumably because of who you're sharing them with). Guess you're one of the lucky ones. > Only times when it was slow it was long time ago when it was on premise and business always skipped upgrading any servers so admins had to run it on tight rope. Nope, even on big hardware it was always interminably slow.
dakiol 3y ago
> What black magic do you have to cast to get devs to look at the documentation? That's not how documentation works (in my experience). Ignoring documentation is fine (perhaps I don't need documentation to get things done?). The problem is having the need of documentation and find that none exists; that's the real issue. If there's no documentation, as an engineer I have 2 options: a) read the codebase, b) ask around. Whatever option takes less time and is more accurate wins (and take into account that the code may contains bugs, so the code is not always a reflection of the intended business use cases... on the other hand no-one may know what the codebase is supposed to do). Documentation is like having a fire extinguisher: hopefully you won't need it most of the time, but if in that single occasion that you need it you find none, well, imagine.
- lordnacho 3y ago
  It's not just whether it exists though. Too much documentation is a thing as well. In a way it's worse, because the reader can't find the thing they are looking for, but the author can always point at where it is when asked. So then the author becomes the index and wonders why they keep getting asked.
mgl 3y ago
Spot on points. Documenting your work seems to be a lost art nowadays in many teams, yet it still is something tangible which we left during our work just next to the source code. We just recetly posted a short text on how we do it at Stratoflow: https://stratoflow.com/writing-software-documentation/ https://stratoflow.com/writing-software-documentation/
epolanski 3y ago
Jm2c but I find placing documentation outside codebases unavoidably a failure. Doesn't keep up. I would include product documentation too.
akomtu 3y ago
Most documentation is poorly written, outdated and disrespects readers' time. However, imagine if every paragraph, every page, every document, would have to be prefaced with a brief summary? It's a small culture shift, but it would make a big difference.
sanderjd 3y ago
Pretty simple, really: Put it in the code. If it is too big to go entirely in the code, summarize it in the code and then link to the full docs (ideally in markdown files inside the repo). Another thing, which you can't really fix yourself, but which I'm still gonna shout into the ether: Ideally you have a browser-based code browsing tool, like GitHub or Gitlab, but one that actually lets people click through method calls into their definition. In my view, that's really the only sane way to read documentation outside of an IDE.
- chinchilla2020 3y ago
  Love this approach. It keeps everything in a 'one stop shop. There is nothing worse than having to chase a tangled graph of google sheets, word documents, readmes, confluences, and figma diagrams in order to understand a piece of code. Just put the whole bloody thing in a little documentation file in the class and be done with it. Better yet, actually use the python docstrings or java docstrings (whatever you call them) and generate the sphinx doc or java doc. Look at this wonderful documentation one-stop-shop for the python flask repo that was autogenerated with sphinx. https://flask.palletsprojects.com/en/2.3.x/ https://flask.palletsprojects.com/en/2.3.x/
  - Silhouette 3y ago
    That strategy does limit your documentation to text though. Sometimes a literal big picture and a few well-considered supporting diagrams can be worth more than a hundred screens of Markdown.
    - lylejantzi3rd 3y ago
      It's also only visible to developers.
      - sanderjd 3y ago
        Everyone should have access to the repo's web interface.
taeric 3y ago
I see two traps here that I largely blame, curious if there are more. First is that documentation is only worth it if you are keeping everything surrounding it stable. Software has been changing a ton in the past few decades such that a lot of documentation from last year is irrelevant. I /think/ this is slowing down, but I can't say for sure. Examples for this are many. Python 2->3, Web frameworks 10 years ago (this one has legit gotten better), general systems management and deployment. Second is that it was easy to get burned by documentation that was really more of a promise of things to come. By that I mean you think you are going to buckle down, research the right way, and make progress. Only to find out that all of the time you just dumped into the "right way" doesn't actually work today. It may work next week, but if you want to do something today, you have to do it the way they did it before. Which is a ton of warnings about how you will need to be prepared to upgrade, at this point. Examples of this, for me personally, have been trying to use XHTML back in the day, WSDL promises, and now OpenAPI.
paulddraper 3y ago
AKA "write-only memory"
timmit 3y ago
I guess it would be better to rephrase it like > Good, Well Indexed and Easy to Find documentation is everything.

gumballindie 3y ago

> What black magic do you have to cast to get devs to look at the documentation? README.md files in each repo, and code level documentation. The readme file can point to useful links, such as diagrams or stuffy documents where needed.

ozim 3y ago
You don't put everything in README.md for the start - once file gets long enough no one will read it the same as bunch of confluence... Links? Parent poster just mentioned he was putting relevant links in JIRA tickets - to work on a feature dev has to open the ticket anyway but suprise-suprise they were not clicking the links. How on earth README.md links will help in such situation.
- gumballindie 3y ago
  Oh when i read documentation i think stuff relevant to getting things to run, architecture and perhaps a little more of whats relevant. Jira tickets and all can be correlated with a proper branching model. I agree, readme files should be concise.

stock_toaster 3y ago

> What black magic do you have to cast to get devs to look at the documentation? Not use Jira and Confluence? More seriously, I have found that confluence is where documentation goes to die. Something about the tooling, the slowness, poor search, admin tools leading to overzealous compartmentalization, not-quite-good plain text format, awkward gui editing tools, versioning system, distance from the code[1]... something... just makes it not really great at being a repository for keeping documentation up to date, or easily usable. [1]: eg. not using the same tools/editors to modify the documentation as you do the code

sodapopcan 3y ago
Ya, there is some wisdom in "don't use Confluence". It's far too heavy for a wiki. Maybe it's fixed by now why should a plain text page show a loading spinner?? I'm personally a fan of one massive README with a table of contents for technical docs. YMMV. Also, definitely link the docs in the description and not the comments. I've found that you should never rely on anyone reading the comments (or re-reading them, at least). Any important info that is surfaced in comments should be moved to the description. Of course, if you're team isn't going to read tickets then that's just a plain problem.
paulddraper 3y ago
There is truth to this. Notion, etc are far more pleasant, readable, and lend for better organization.
smcleod 3y ago
Yeah confluence and jira both need to go away, both of them make it very hard to find information and feel like such a burden to use.

TylerE 3y ago

Not stuffing it into some horrible slow "enterprise" webapp would be a start.

ozim 3y ago
Are we using the same Confluence and JIRA - I don't see it being slow as we use cloud. Only times when it was slow it was long time ago when it was on premise and business always skipped upgrading any servers so admins had to run it on tight rope.
- lmm 3y ago
  > Are we using the same Confluence and JIRA - I don't see it being slow as we use cloud. Well no we're not - if you're using "cloud" then you get randomly assigned an instance, some of them are fast and some of them are slow (presumably because of who you're sharing them with). Guess you're one of the lucky ones. > Only times when it was slow it was long time ago when it was on premise and business always skipped upgrading any servers so admins had to run it on tight rope. Nope, even on big hardware it was always interminably slow.

dakiol 3y ago

> What black magic do you have to cast to get devs to look at the documentation? That's not how documentation works (in my experience). Ignoring documentation is fine (perhaps I don't need documentation to get things done?). The problem is having the need of documentation and find that none exists; that's the real issue. If there's no documentation, as an engineer I have 2 options: a) read the codebase, b) ask around. Whatever option takes less time and is more accurate wins (and take into account that the code may contains bugs, so the code is not always a reflection of the intended business use cases... on the other hand no-one may know what the codebase is supposed to do). Documentation is like having a fire extinguisher: hopefully you won't need it most of the time, but if in that single occasion that you need it you find none, well, imagine.

lordnacho 3y ago
It's not just whether it exists though. Too much documentation is a thing as well. In a way it's worse, because the reader can't find the thing they are looking for, but the author can always point at where it is when asked. So then the author becomes the index and wonders why they keep getting asked.

mgl 3y ago

Spot on points. Documenting your work seems to be a lost art nowadays in many teams, yet it still is something tangible which we left during our work just next to the source code. We just recetly posted a short text on how we do it at Stratoflow: https://stratoflow.com/writing-software-documentation/ https://stratoflow.com/writing-software-documentation/

epolanski 3y ago

Jm2c but I find placing documentation outside codebases unavoidably a failure. Doesn't keep up. I would include product documentation too.

akomtu 3y ago

Most documentation is poorly written, outdated and disrespects readers' time. However, imagine if every paragraph, every page, every document, would have to be prefaced with a brief summary? It's a small culture shift, but it would make a big difference.

sanderjd 3y ago

Pretty simple, really: Put it in the code. If it is too big to go entirely in the code, summarize it in the code and then link to the full docs (ideally in markdown files inside the repo). Another thing, which you can't really fix yourself, but which I'm still gonna shout into the ether: Ideally you have a browser-based code browsing tool, like GitHub or Gitlab, but one that actually lets people click through method calls into their definition. In my view, that's really the only sane way to read documentation outside of an IDE.

chinchilla2020 3y ago
Love this approach. It keeps everything in a 'one stop shop. There is nothing worse than having to chase a tangled graph of google sheets, word documents, readmes, confluences, and figma diagrams in order to understand a piece of code. Just put the whole bloody thing in a little documentation file in the class and be done with it. Better yet, actually use the python docstrings or java docstrings (whatever you call them) and generate the sphinx doc or java doc. Look at this wonderful documentation one-stop-shop for the python flask repo that was autogenerated with sphinx. https://flask.palletsprojects.com/en/2.3.x/ https://flask.palletsprojects.com/en/2.3.x/
- Silhouette 3y ago
  That strategy does limit your documentation to text though. Sometimes a literal big picture and a few well-considered supporting diagrams can be worth more than a hundred screens of Markdown.
  - lylejantzi3rd 3y ago
    It's also only visible to developers.
    - sanderjd 3y ago
      Everyone should have access to the repo's web interface.

taeric 3y ago

I see two traps here that I largely blame, curious if there are more. First is that documentation is only worth it if you are keeping everything surrounding it stable. Software has been changing a ton in the past few decades such that a lot of documentation from last year is irrelevant. I /think/ this is slowing down, but I can't say for sure. Examples for this are many. Python 2->3, Web frameworks 10 years ago (this one has legit gotten better), general systems management and deployment. Second is that it was easy to get burned by documentation that was really more of a promise of things to come. By that I mean you think you are going to buckle down, research the right way, and make progress. Only to find out that all of the time you just dumped into the "right way" doesn't actually work today. It may work next week, but if you want to do something today, you have to do it the way they did it before. Which is a ton of warnings about how you will need to be prepared to upgrade, at this point. Examples of this, for me personally, have been trying to use XHTML back in the day, WSDL promises, and now OpenAPI.

paulddraper 3y ago

AKA "write-only memory"

timmit 3y ago

I guess it would be better to rephrase it like > Good, Well Indexed and Easy to Find documentation is everything.