Hacker News Reader

brwron Show HN: LogRocket – Record and Replay for Redux Apps

As a Sentry user, this is exciting! Any idea when this will make it to production?

brwron Show HN: LogRocket – Record and Replay for Redux Apps

Good call! I just whitelisted LogRocket instead. :)

brwron Show HN: LogRocket – Record and Replay for Redux Apps

Hey. The support button on the sidebar doesn't go anywhere. How do I ping you?

brwron Show HN: I'm writing the Modular JavaScript book series

At least for me, security isn't the concern. The problem is that I have no idea what I'm recommending. Have you considered letting users read a bit before asking for the Tweet?

I've been a PonyFoo reader for a long time. You're obviously a talented guy. But I still want to get an idea of what you have produced before tweeting about it.

That said, I'm very much looking forward to "Mastering Modular JavaScript" and "Deploying Modern JavaScript Apps"! :) I'm sure you know better than most that the internet is full of unappreciative haters, but keep up the fantastic work. There are many of us who have benefited from your writing in amazing ways.

brwron Peter Thiel, YC, and Hard Decisions

Is there a way for the mods to protect the post from user flags? Normally, user flags are a good thing. That doesn't seem to be true in this case, though.

brwron Ask HN: Is web programming a series of hacks on hacks?

Web developer is not ideal. That is more of a people issue than it is a technology issue.

Whatever our collective gripes about JavaScript, HTML, and CSS, we all know how to use them. We know how to handle cross-browser compatibility and different screen sizes. What we need to do a better job at -- and I think this is the root of the problem you're describing -- is pushing back on businesses wanting to ship features too quickly.

We've all been at places where no one values good work on the client. The C-levels want to get things out the door as quickly as possible. They complain that our work has bugs and we tell them "Well that's what you get for telling me I had 3 days."

Because of this heat, front-end engineers rarely engineer their software. As you put it, they hack it together on top of libraries that have been hacked together by others. The solution is to take the time required to do things correctly. That means testing. That means not shipping features so we have time to refactor and upgrade frameworks. That means paying attention to performance and developing tools for debugging errors in production. If we want web development to get better, these things can't be afterthoughts. They must be considered before we say something is "done" and ship it to production.

brwron Ask HN: Is it a good idea to build a Single Page App with Django?

I've spent a lot of time working with Django as a backend and AngularJS powering the client. It's definitely not a bad combination.

That said, in my personal projects, I lean towards letting Django handle almost all of the client experience too. There are exceptions for areas that are inherently interactive (e.g. WSYIWYG editor), but the vast majority of my projects involve static content. To me, the complexity and overhead of using a JS library/framework outweighs any benefits the library/framework might offer.

brwron Engineering offices

I tend to agree with this. I've never had a private office with a door that closes, so how would I know what I'm missing out on? That said, the idea does sound nice and I'd definitely try it out if I had the opportunity.

brwron Ask HN: How does your team write documentation? What tools do you use?

I'd definitely be interested. :)

brwron Ask HN: How does your team write documentation? What tools do you use?

What you described is what I'm hoping to see over the next few months. I joined the company recently, so there's still a lot of internals that I don't fully understand.

brwron Ask HN: How does your team write documentation? What tools do you use?

We've already have internal discussions about whether it makes sense to make documentation part of our ticketing system (we use Pivotal Tracker). Everyone seems to agree that it's the only way the docs will ever get updated. 30% is a lot though!

brwron Ask HN: How does your team write documentation? What tools do you use?

Thanks for the insight!

Regarding documentation covering an overarching vision for the code: It is my experience that the person best-suited to write these docs -- i.e. The person who knows the codebase the best -- is always in demand at the company. This person has very little free time and I doubt they want to spent it writing docs for everyone else.

Is that something you've noticed?

brwron Ask HN: How does your team write documentation? What tools do you use?

We're hiring? :)

brwron Ask HN: How does your team write documentation? What tools do you use?

You're way more hardcore than I am. I tried LaTeX once. I still have scars.

brwron Ask HN: How does your team write documentation? What tools do you use?

Is your company using the Office 365 version of MS Word? I wonder if it would be possible to automatically convert an MS Word file to Markdown :o

brwron Ask HN: How does your team write documentation? What tools do you use?

It's not a bad solution, unless you're the guy who knows everything. And I don't mean that in a facetious way; some companies have one person that knows everything about the codebase. We've got one of those guys on our team. I think he sometimes gets sick of answering noob questions, because we've been growing like wildfire over the past 6 months.

brwron Ask HN: How does your team write documentation? What tools do you use?

What makes Mkdocs easy to get started? I'm not familiar with it, so any insight you have is great. We need something that requires minimal commitment from the team, you know?

brwron Ask HN: How does your team write documentation? What tools do you use?

I've thought about this a bit and personally came to the conclusion that extracting inline comments is a bad idea. They are inline for a reason.

By way of example, I frequently use inline comments to discuss things like how a given class is architected, which (if any) popular design patterns are used, usage examples, etc. This stuff is really only relevant when you have the file open in your editor, so inlining the comments makes perfect sense.

brwron Ask HN: How does your team write documentation? What tools do you use?

Does Bitbucket's wiki support search? Github's doesn't and thats one reason it was vetoed.

brwron Ask HN: How does your team write documentation? What tools do you use?

Hey! Docily sounds cool, but we've already vetoed a few options because we want our documentation de-coupled from our codebase. We want the entire company (not just product and engineering) to be able to use the system we go with.

brwron Ask HN: How does your team write documentation? What tools do you use?

That's really good advice.

I also want to add a ton of documentation around the "Why?" factor. Why did we make this decision? Why are we using this technology? etc.

The first question is always "How do I do this?". The second question is almost always "Why do I have to do it that way?". ;)

brwron Ask HN: How does your team write documentation? What tools do you use?

These stories just make me more and more sad. Haha. What are you using these days?

brwron Ask HN: How does your team write documentation? What tools do you use?

I feel like you need a hug. :( That sounds absolutely terrible!

brwron Ask HN: How does your team write documentation? What tools do you use?

One of the requirements we're facing internally is having a system that can be used by the entire company and not just the engineering team. Unfortunately, the options that have been presented are all wikis with poor UI. :(

brwron Ask HN: How does your team write documentation? What tools do you use?

That's so cool! It blows my mind that the search is done in-browser.

brwron Ask HN: How does your team write documentation? What tools do you use?

Over time I've noticed that a lot of software developers aren't good documentation writers. I'm not saying this is good or bad, but it is a statement I believe to be true.

With that said, what advantages are there to removing the bottleneck of "I updated the docs, please everyone check before release and send me your comments"? To me, personally, letting anyone update the docs without review sounds like a recipe for trouble.

brwron Ask HN: How does your team write documentation? What tools do you use?

Thanks for the reply!

Two questions for you:

1) I agree that documentation has to be a visible part of the workflow, but getting buy-in from the whole team is difficult even with small decisions. What have you done to get your team onboard with writing docs?

2) Why are wikis where docs go to die?

brwron Ask HN: How does your team write documentation? What tools do you use?

Sadface. :(

I know your feels. I've worked at companies that do things because "that's what people use". Never fun.

What sort of documentation do you and your team maintain other than your API docs?

Also: +1 for Sphinx! <3 ReST

brwron Ask HN: How does your team write documentation? What tools do you use?

What do you keep in the Wiki?

brwron Ask HN: How does your team write documentation? What tools do you use?

That's really interesting. Wasn't expecting to hear Gitbook. Why Githbook?