Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Tools We Use To Stay Afloat

colloq.io

Post reply on HN
Print view View original

31–38 of 38 posts

Re: The Tools We Use To Stay Afloat

#31

Post by enraged_camel »

wpietri wrote: post #23
awinter-py wrote: post #12

I wish this were an article about some hot new documentation tool instead of another misguided psalm to slack & kanban. Making docs sexy would be a big quality of life boost for programmers and the people who love them (i.e. project managers and users of software).

I used to feel that way, but now generally don't. Most documentation is effectively duplication of something already expressed in the code. That means that whenever you add docs, you are multiplying the effort needed to change things in the future. You also create opportunities for the various expressive duplications to diverge, causing untold confusion. Now documentation is always a last resort for me. That's a sham…

I don't think the things you listed, even when combined, are sufficient substitutes for well-written documentation.

The fact of the matter is that, for humans, plain English is always much easier to understand than computer code. The more complex the code, the more true that is going to be. You can use all the friendly function names and object names and file layouts you want. At the end of the day, it is not going to be enough for someone who is not familiar with that part of the system to understand it quickly and to the appropriate level of detail. This is especially true if you have junior-level or intermediate-level people on your team. It is also true if you ever end up coming back to some piece of code you yourself wrote a year ago.

Furthermore, documentation can provide additional value by including examples of code usage in different settings that you may not have covered in your test cases due to not being immediately relevant. It can contain links to other websites and have embedded images of system diagrams or data flow. It can also describe third-party systems your code has to interact with and various bugs and unconventional behavior that may exist in those systems that your code has to account for.

Yes, documentation involves more upfront effort. IMO the correct way to deal with that is to include that in project estimates, and to not mark tasks and features to be "done" until their documentation is written. Same with revisions and bug fixes. I understand the feeling that it duplicates logic already expressed in the code. But look at it this way: code is for computers. Documentation is for humans.

Re: The Tools We Use To Stay Afloat

#32

Post by dragonwriter »

awinter-py wrote: post #29
wpietri wrote: post #23

Earlier quoted context omitted.

I used to feel that way, but now generally don't. Most documentation is effectively duplication of something already expressed in the code. That means that whenever you add docs, you are multiplying the effort needed to change things in the future. You also create opportunities for the various expressive duplications to diverge, causing untold confusion. Now documentation is always a last resort for me. That's a sham…

I agree. Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant. Good docs will resemble or contain a test suite. I agree with your point about blogposts -- publish date is like a sell-by date, makes it clear when the post has gone stale. Getting insiders to read docs is also hard. Not every piece of code is worth documenting. But I think highly critical and highly reused code is w…

> Docs/code impedance mismatch is a problem that a docs tool needs to solve to stay relevant.

It's not an impedance mismatch (which results from difference in the structural representations supported by different systems), it's just a content mismatch. And it's not a tooling problem, it's a process problem. Documentation is the single source of truth for intent, and development process must respect that.

This becomes more and more important the more people who aren't developers need to understand the logical function of the system.

Re: The Tools We Use To Stay Afloat

#33

Post by dbg31415 »

hobofan wrote: post #18
dbg31415 wrote: post #9

ZenHub is free for teams under 5 people. And it's great. * ZenHub - Agile GitHub Project Management || https://www.zenhub.com/ Also I use a tool that keeps labels in sync across GitHub repos. * github-label-sync || https://www.npmjs.com/package/github-label-sync Harvest for time tracking. * Simple Online Time Tracking Software - Harvest || https://www.getharvest.com/ Red Pen for annotations. (Does't integrate with an…

Time tracking seems very microcontrolish for such a small team, and doesn't really seem worth the overhead. If the team includes freelancers, that's of course a different thing.

You track time so you have metrics and can back up your opinions with facts.

"We need more developers..."

Ok, show me how much work we are doing... and where the hours are being spent... so we can figure out how to optimize and recruit more folks.

There isn't a team out there that can afford not to track how they spend their time. Not tracking hours is like not brushing your teeth... It's such a simple thing, takes 3 minutes a day.

Re: The Tools We Use To Stay Afloat

#34

Post by dbg31415 »

anselmh wrote: post #16
dbg31415 wrote: post #9

ZenHub is free for teams under 5 people. And it's great. * ZenHub - Agile GitHub Project Management || https://www.zenhub.com/ Also I use a tool that keeps labels in sync across GitHub repos. * github-label-sync || https://www.npmjs.com/package/github-label-sync Harvest for time tracking. * Simple Online Time Tracking Software - Harvest || https://www.getharvest.com/ Red Pen for annotations. (Does't integrate with an…

Thanks for the list, it’s quite good! However, our point is to not use third-parties for things where we don’t need it. The point of the article is to show that you can use Github solely for project management without a third-party service. But I completely agree with you: If you don’t like the little extra-work we do to achieve that with just github.com, it’s probably right to add another tool like ZenHub or waffle.…

Gonna rant a bit... GitHub boards cost time. No one should use them. They're just an inferior option to ZenHub (or even Waffle or Asana or any number of other "board" interfaces you can tack on to GitHub). I've wasted my team's time on GitHub boards... everyone quickly demanded we go back to ZenHub.

Most projects have multiple repositories, right? But GitHub boards have it so that each board is based on one repo. Stupid. You want to see a project view of all your repos at once... front-end, back-end, deployment, whatever... not 4 or 5 separate views on it.

I feel like GitHub REALLY dropped the ball on not having a board forever, then putting out such a "beta-feeling" board. They should have just bought ZenHub -- still time... but literally any tool out there makes the boards work better than default GitHub.

ZenHub is free for small teams, and I'd argue that anyone can afford $5 / month / user. Budget $150 / month / user for any team for tools -- seems about right.

Re: The Tools We Use To Stay Afloat

#35

Post by wpietri »

enraged_camel wrote: post #31
wpietri wrote: post #23

Earlier quoted context omitted.

I used to feel that way, but now generally don't. Most documentation is effectively duplication of something already expressed in the code. That means that whenever you add docs, you are multiplying the effort needed to change things in the future. You also create opportunities for the various expressive duplications to diverge, causing untold confusion. Now documentation is always a last resort for me. That's a sham…

I don't think the things you listed, even when combined, are sufficient substitutes for well-written documentation. The fact of the matter is that, for humans, plain English is always much easier to understand than computer code. The more complex the code, the more true that is going to be. You can use all the friendly function names and object names and file layouts you want. At the end of the day, it is not going t…

I should be clear that I like good documentation, and will happily write it when necessary. It's just that over the years, I've a) found a lot of ways to make it unnecessary, b) grown to despise useless or out of date docs, which is the bulk of what I see, and c) grown very tired of writing documentation that people end up not reading.

> [...] plain English is always much easier to understand than computer code [...] This is especially true if you have junior-level or intermediate-level people on your team.

This is why I'm a big fan of collective code ownership, pair programming, and frequent pair rotation. That has a variety of benefits. It also has substantial advantages over documentation. A big piece of which is that the need for documentation is always speculative, whereas answering a question always works from a confirmed need.

> It is also true if you ever end up coming back to some piece of code you yourself wrote a year ago.

This is what I use tests and journals for. Well-written tests are essentially machine-verifiable documentation. They tell me what the intent of the system is. If I want to know the history of the intent, then I turn to my journals.

> But look at it this way: code is for computers. Documentation is for humans.

I couldn't disagree more. As Martin Fowler says: “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”

Code and tests are primarily means of communication between developers. They have the constraint that they should result in a running system. But we stuff most of the work of that into compilers, optimizers, and run times. Our tools are -- and should be -- optimized for human productivity. And since programming is mostly a team sport, the biggest value of our tools is in how they enable that teamwork.

Re: The Tools We Use To Stay Afloat

#36

Post by ethbro »

wpietri wrote: post #35
enraged_camel wrote: post #31

Earlier quoted context omitted.

I don't think the things you listed, even when combined, are sufficient substitutes for well-written documentation. The fact of the matter is that, for humans, plain English is always much easier to understand than computer code. The more complex the code, the more true that is going to be. You can use all the friendly function names and object names and file layouts you want. At the end of the day, it is not going t…

I should be clear that I like good documentation, and will happily write it when necessary. It's just that over the years, I've a) found a lot of ways to make it unnecessary, b) grown to despise useless or out of date docs, which is the bulk of what I see, and c) grown very tired of writing documentation that people end up not reading. > [...] plain English is always much easier to understand than computer code [...]…

The biggest value in documentation to me has always been efficiency in understanding: that usually means documenting at the architecture / "components as black boxes" level.

I could trace through to see how someone glued something together without having a hint what I'm looking for, or I could get the architecture gist and then generally know where the thing I should be looking at is.

To me, this delivers two benefits. (1) Reduced redundancy / potential for divergence (as you mentioned above), as you're not re-documenting code but rather documenting at a higher level. (2) Reduced churn, as architecture changes more slowly than code, and generally an arch change will have some organizational process before being made (where docs can be updated).

Disclaimer: This is coming from a place of diving into a lot of client systems with really poor or utterly lacking documentation.

Re: The Tools We Use To Stay Afloat

#37

Post by tsutsarin »

jameshart wrote: post #28
kingbirdy wrote: post #3

The branch deploy sounds pretty interesting, I wish there was more detail on it than just a footnote

We're doing the same for microservice deployments to kubernetes, using Jenkins' multibranch pipeline - Jenkins just watches the git repo, and any commit to a branch that contains a Jenkinsfile gets built. At the end of the build process, we publish a docker image tagged with the branch and build number, and then use helm to upgrade or create a deployment in a kubernetes cluster, tagged to run the just-published docke…

Is your Jenkinsfile open source? I'm trying to make something similar using Helm charts, would use that as reference.

Re: The Tools We Use To Stay Afloat

#38

Post by wpietri »

ethbro wrote: post #36
wpietri wrote: post #35

Earlier quoted context omitted.

I should be clear that I like good documentation, and will happily write it when necessary. It's just that over the years, I've a) found a lot of ways to make it unnecessary, b) grown to despise useless or out of date docs, which is the bulk of what I see, and c) grown very tired of writing documentation that people end up not reading. > [...] plain English is always much easier to understand than computer code [...]…

The biggest value in documentation to me has always been efficiency in understanding: that usually means documenting at the architecture / "components as black boxes" level. I could trace through to see how someone glued something together without having a hint what I'm looking for, or I could get the architecture gist and then generally know where the thing I should be looking at is. To me, this delivers two benefit…

Sure, but no documentation here will be as efficient as an expert having a conversation with you and answering your questions. I'd much rather have a few whiteboard conversations and maybe some pair programming time, and that is cheaper and easier for everybody then speculative production of documentation.

If the choices are only "shitty code with no docs" and "shitty code with good docs", I'll definitely take the latter. And if I'm rolling a team off a project, I'm happy to take some time to write some high-level docs for the people who will next pick it up. That's a one-time expense with documentation written for a defined audience.

But when I'm picking up a system and the original team is gone, I'd much rather have good code and good tests over good docs.

And honestly, I'm not sure I've even inherited a system with good docs. I have seen things that managers probably thought were good docs. And I've seen things that the developers intended to be good docs, and might have even been good once upon a time. But by the time I get to them, it's either the "we were told to write docs" garbage that is useless, or stuff that's so far out of date that it's just as often misleading as helpful.

Post reply on HN