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

21–30 of 38 posts

Re: The Tools We Use To Stay Afloat

#21

Post by wpietri »

bdcravens wrote: post #10
hgdsraj wrote: post #8

Why don't you guys use pivotal tracker? Way better ticket management, integrates with github

We've use Pivotal Tracker before, and it always felt challenging to have more than a basic description/discussion (maybe that's the point), but most tools like Jira, Github Issues, Trello, etc, facilitate a larger view.

It is definitely the point.

One of the basic notions in the school of thought that Tracker comes out of is that team interaction is valuable and to be encouraged. So making a tool that makes it easy for people to not talk undermines the broader goal.

One of the basic insights of the Agile movement (R.I.P.) about Waterfall is that processes structured around documentation rather than collaboration have a lot of subtle bad effects that gradually destroy characteristics you'd like your teams to have. E.g., responsiveness to change, systemic effectiveness, resilience to failure, low overhead, ability to ship frequently, ability to deliver customer value.

That's why when I set things up I generally drive things off of index cards. [1] Those are obviously insufficient, which forces people to discuss and collaborate. (That's in contrast to more voluminous documentation, which is subtly insufficient.)

[1] E.g.: http://williampietri.com/writing/2015/the-big-board/

Re: The Tools We Use To Stay Afloat

#22

Post by vmasto »

e1g wrote: post #14
vmasto wrote: post #11

Earlier quoted context omitted.

How do you handle the database? Do you reuse the one on staging or create a new instance with prepopulated data? If the former how do you deal with migrations and schema edits?

Yes, the db has been the most challenging aspect for us. We have 3 situations - 1. "Common baseline". With a relatively stable product, most branches (as in ~51%) do not impact the schema. For testing / QA purposes, these share one central QA db and pollute each out. Turns out, a lot of the times this is quite ok because the PR is about how the data is displayed, or improved logging, or UX change, or a security layer…

Thanks for taking the time to answer!

FWIW this topic would make for a great technical post/how-to.

I also seem to recall that Automattic does this with their front end (calypso) which handles wordpress.com

Re: The Tools We Use To Stay Afloat

#23

Post by wpietri »

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 shame, as I enjoy writing. Instead I try to put knowledge in existing places, like unit tests, acceptance tests, method names, object names, code structure, file layout, in-app text, and all of the other little things I'm already doing along the way. Only if I can't put something there will I write docs, and then reluctantly and with a feeling I probably missed a chance to minimize duplication.

The only documentation I still write without reservation is stuff that obviously doesn't have to keep up with the project as it changes. E.g., personal journals and project blogs are great, in that everybody understands those are out of date right after they're written.

Re: The Tools We Use To Stay Afloat

#24

Post by hobofan »

awinter-py wrote: post #20
hobofan wrote: post #19

Earlier quoted context omitted.

Best tip for docs in small teams: Have a server running in the local network that pulls the latest develop branch, renders it and serves it on the network for each project. For microservices I would recommend API Blueprint, for normal libraries, whatever is the language standard. Really cuts down the friction of getting to the docs, since you don't have to do all those steps on you local machine anymore whenever you…

hadn't heard of API blueprint -- pretty cool. in addition to tools for documenting interfaces (i.e. APIs), I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. In type safety terms, this is like the difference between function signatures that verify inputs & outputs vs something like coq/TLA that can verify more advanced properties of your program. Configuration…

> I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases.

> Configuration is particularly difficult to document in 2017 -- if you solve that problem you fix a lot of migraines.

Could you expand on those points a bit more? As for the first one, it sounds vaguely like https://deckard.ai, but I feel you could also mean something entirely different. (Disclamier: I know the founders of Deckard very well.)

Re: The Tools We Use To Stay Afloat

#25

Post by jacques_chester »

awinter-py wrote: post #20
hobofan wrote: post #19

Earlier quoted context omitted.

Best tip for docs in small teams: Have a server running in the local network that pulls the latest develop branch, renders it and serves it on the network for each project. For microservices I would recommend API Blueprint, for normal libraries, whatever is the language standard. Really cuts down the friction of getting to the docs, since you don't have to do all those steps on you local machine anymore whenever you…

hadn't heard of API blueprint -- pretty cool. in addition to tools for documenting interfaces (i.e. APIs), I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. In type safety terms, this is like the difference between function signatures that verify inputs & outputs vs something like coq/TLA that can verify more advanced properties of your program. Configuration…

Some of my colleagues in Pivotal Labs swear by Spring Cloud Contract[0], but I haven't used it in anger myself. It seems to be what you want -- an independent statement of protocol that's shared between server and client codebases, with code-generation to help each.

[0] https://github.com/spring-cloud/spring-cloud-contract

Re: The Tools We Use To Stay Afloat

#26

Post by jacques_chester »

mminer wrote: post #6
kingbirdy wrote: post #3

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

In a previous job, I built (what sounds like) a similar system. From a web UI, coworkers would see a list of recent commits, from which they could fire up an instance of the web app on demand. This created a new Docker container running the server that they could navigate to. A unique port distinguished each instance. Git tags indicated particularly important commits, e.g. new features that required more extensive te…

That is pretty nifty.

Re: The Tools We Use To Stay Afloat

#27

Post by jacques_chester »

bdcravens wrote: post #10
hgdsraj wrote: post #8

Why don't you guys use pivotal tracker? Way better ticket management, integrates with github

We've use Pivotal Tracker before, and it always felt challenging to have more than a basic description/discussion (maybe that's the point), but most tools like Jira, Github Issues, Trello, etc, facilitate a larger view.

Tracker is very opinionated and is deliberately trying to not be the be-all and end-all for software projects. It's really closely tuned to how Pivotal works: XP with Lean trimmings in small teams with a product manager, designer and engineers.

The downside is that because it is deliberately limited, now and then you will find that you sorely miss something. Often those missing features are recreated with conventions around tagging or release markers. But tagging conventions are not the same as a first-class feature, for good or ill.

JIRA is massively more featuresome and flexible. These days it's grown into a workflow middleware which comes with a bug tracker as the first application installed. For some organisations that will make more sense.

Disclosure: I work for Pivotal, but not on Tracker.

Re: The Tools We Use To Stay Afloat

#28

Post by jameshart »

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 docker image. Our cluster's running in AWS and has a package deployed to it called 'area53' which can set up route 53 DNS records for kubernetes services automatically.

Upshot of all that is that if you create and push a new branch called 'foo', a few minutes later that branch's code is up and running in AWS, under the name 'service-foo.dev.example.com'. We can then automatically run integration tests against that endpoint.

Best part is that the build process defined by the jenkinsfile, and the deployment defined by the helm chart, all live in the source, so you can play with them on a branch. Want to add another testing step to the build process? Branch, add it to the jenkinsfile, and your build pipeline change gets executed just for your branch, without stopping other branches from building. Once you're happy with the addition, merge the change and now every future branch gets that extra deployment step. Likewise if you modify the deployment chart, you can test it in a branch.

Re: The Tools We Use To Stay Afloat

#29

Post by awinter-py »

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 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 worth documenting, in part for programmers and in part so that non-coder stakeholders can understand the details of the product (i.e. 'sell what you make' if they're on the sales team).

Re: The Tools We Use To Stay Afloat

#30

Post by awinter-py »

hobofan wrote: post #24
awinter-py wrote: post #20

Earlier quoted context omitted.

hadn't heard of API blueprint -- pretty cool. in addition to tools for documenting interfaces (i.e. APIs), I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. In type safety terms, this is like the difference between function signatures that verify inputs & outputs vs something like coq/TLA that can verify more advanced properties of your program. Configuration…

> I'm interested in tools that document behavior (both desired & observed) and integrate it back to codebases. > Configuration is particularly difficult to document in 2017 -- if you solve that problem you fix a lot of migraines. Could you expand on those points a bit more? As for the first one, it sounds vaguely like https://deckard.ai , but I feel you could also mean something entirely different. (Disclamier: I kno…

By 'behavior' I mean two things:

(1) contractual behavior (what you want/expect) can be marked up in comments that generate docs but are also readable inline in the code.

And (2) actual behavior in the wild from monitoring, tracebacks, profiling. Would be cool if IDEs could drop that next to a function so I can ask 'is this slow', 'does this ever get called'.

Re: configuration I'm saying it's not always clear what a config setting does, and esp. how related config settings combine. Having standard types for configuration would let us generate docs for which part of the program are affected by a config setting; at least provide a starting point for understanding the flag's behavior.

Post reply on HN