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

Stack Overflow for Teams

stackoverflow.com

Post reply on HN
Print view View original

151–160 of 163 posts

Re: Stack Overflow for Teams

#151

Post by your-nanny »

chatmasta wrote: post #123
snarf21 wrote: post #121

Earlier quoted context omitted.

The conclusion I've come to in regards to comments is that each function should have a comment about WHY it is needed. As you said the code will change and exactly what it does will morph, but the why describes the architecture (somewhat) and hints at the abstraction model.

Please no, do not comment every function. Each function should average 5-10 lines, with clearly defined separation of concerns, and a descriptive name that inherently describes any writes/reads of the function. In the rare case where it makes sense to have a massive function, and you can’t break it into smaller functions within its scope, then maybe it makes sense to use a comment. Adopting a policy of commenting eve…

Is this philosophy of code commenting the antithesis of literate programming?

Re: Stack Overflow for Teams

#152

Post by Noumenon72 »

farkas wrote: post #124
tedivm wrote: post #52

Earlier quoted context omitted.

It's only "half the price" if you ignore the cost of Confluence itself. The Atlassian people are also historically awful at building out features that make hosting their products easier (for example, they've ignored a request for a "read only" mode for about 12 years now [1]). The simple fact that it is a product that is made by someone other than Atlassian is a huge selling point. [1] https://jira.atlassian.com/brow…

FYI that we're implementing read-ony mode in our data center product line, and we've also got various knowledge base articles for how to achieve this should you need it: https://confluence.atlassian.com/confkb/how-to-make-confluence-read-only-311920317.html In any software, you've always got old requests that haven't been filled. We're just public about it. StackOverflow has the same issue here: https://meta.stackexc…

I have never had the opportunity to tell anyone at Atlassian how much I love Confluence. There are so many cool technical feats that improve my experience, like being able to open an embedded spreadsheet in Excel and having it update the version on the page when you hit save. So many things that aren't natural for the web are seamless, like indent levels and accepting pasted images. So many organizational tools like excerpts and child view macro. So many usability features like attachment versioning and keyboard shortcuts.

It takes a great company to make such a great product so easy to use. Thank you.

Re: Stack Overflow for Teams

#153

Post by kamaal »

parvenu74 wrote: post #38

Seems like "yet another tool to try to offset the problem of requirements, code, and architectural decisions not being adequately documented for future staff to understand." Sometimes I wonder if software teams should add technical writers embed with developers, architects, QA, and BA assets to actually document All The Things and keep documentation up to date. Yes, that will mean re-writing documentations as people…

>>Sometimes I wonder if software teams should add technical writers

Part of CMM level 5 process was things like 'Knowledge teams' which did exactly that.

Agile eat CMM for lunch though.

Re: Stack Overflow for Teams

#154

Post by colshrapnel »

pugworthy wrote: post #102
tekkk wrote: post #4

My question is, is this better than your self-hosted wiki? At least that's cheaper and isn't a vendor lock-in. Sure wiki doesn't have the best possible UI and the UX might be too so-and-so. If I were in a position to buy this kind of service I'd still want something more out of it. Maybe if it offered a way to export Slack threads into SO as questions so they wouldn't get lost. Sure you could generate those questions…

If your goal is to post problems and associated solutions, yes it is better than a Wiki. First, it gives you a template to post in - you are not given a blank page and told "document this" Second, it encourages you to document single, smaller, focused pieces of information. You're not being asked or expected to write a multipage document, you're being asked to write a single entry in what essentially is a crowd sourc…

If your goal is to post, then SO is excellent. But if your goal is also to read, there are questions. Nobody ever tried to use Stack Overflow without Google yet. given all its bell and whistles are intended for those who want to post, there are questions yet to answer.

Re: Stack Overflow for Teams

#155

Post by falcor84 »

htaoerth29th wrote: post #144
tootie wrote: post #56

Earlier quoted context omitted.

I think the win would be in making the answers more findable. Confluence is great for writing documents and laying out pages in a hierarchy, but full-text search is still very hit and miss. Especially when you have 50 projects that all have the same keywords and 49 of them are irrelevant.

> Confluence is great for writing documents Citation needed. I use it almost daily and it's essentially write-only and pretty unusably so at that.

>> Confluence is great for writing documents

>... it's essentially write-only

Seems like there's no disagreement here :)

Anyway, as I see it, as someone who has written quite enough if it, most software documentation is write-only 99% of the time; but it is occasionally very handy to have that documentation written by the original developers when shit really hits the fan.

Re: Stack Overflow for Teams

#156

Post by OpenDrapery »

kamaal wrote: post #153
parvenu74 wrote: post #38

Seems like "yet another tool to try to offset the problem of requirements, code, and architectural decisions not being adequately documented for future staff to understand." Sometimes I wonder if software teams should add technical writers embed with developers, architects, QA, and BA assets to actually document All The Things and keep documentation up to date. Yes, that will mean re-writing documentations as people…

>>Sometimes I wonder if software teams should add technical writers Part of CMM level 5 process was things like 'Knowledge teams' which did exactly that. Agile eat CMM for lunch though.

What is the general opinion of CMM these days? I always associate it with UML diagrams for some reason. There was a time when the industry really wanted software to be fully specified. Seems like most people gave up on that dream, when agile came around and said "embrace change", along with the tenants.

But, alas, the pendulum swings. I think it's swinging back toward "I sure wish we didn't have to depend on finding skilled people, and our process was so bulletproof we could plug in any old schmuck and we can just continue to print money".

Damn, the business man is greedy.

Re: Stack Overflow for Teams

#157

Post by rwilsonperkin »

Someone1234 wrote: post #92
rwilsonperkin wrote: post #69

We've been running this in beta for a couple months now, happy to answer questions about it. The SO team has been super helpful during the process.

Roughly how many programmers do you have? What difficult has it been to get people to participate (on either end of the scale)?

About 50 programmers, yes we've found that it wasn't natural for people to start asking their questions there and that we (the team that opened the beta) tend to seed Q&A there to drive people to the tool.

Re: Stack Overflow for Teams

#158

Post by rwilsonperkin »

nwsm wrote: post #110
rwilsonperkin wrote: post #69

We've been running this in beta for a couple months now, happy to answer questions about it. The SO team has been super helpful during the process.

What did you have in place before this (wiki, Slack, Yammer or something like it) if anything? Is this better than finding the right person to ask, or posting in slack or something? In my org we have a wiki on topics and if that fails an "experts" list with people to contact for further help. There is also a yammer group for asking questions, but that is rarely used. I think this could be helpful, but whether or not…

Our documentation is split up between markdown files in-repo and a wiki (Confluence) with lots of assorted information. Interestingly we do the same kind of thing with an "experts" list, but with a focus for on-call engineers so they know who to contact if something's broken.

A lot of people still have a natural inclination to just post their questions in chat - probably because it's lower friction than typing up a question and then posting that in chat. We've been trying to shift this by re-posting people's questions in SO and answering them there. It's been mostly helpful, but I'd say we still have a ways to go in shifting people towards SO.

Re: Stack Overflow for Teams

#159

Post by MediumD »

Noumenon72 wrote: post #149
htaoerth29th wrote: post #143

Earlier quoted context omitted.

> In a wiki, at least I can follow the structure to find relevant pages Wow! You have much more disciplined coworkers than most of us, then. I've been at my current employer for about 13 years now. We've gone through 3 or 4 different wikis. Right now we're split between Confluence (worst wiki software I've ever used) and an in-house solution. I can't find a god damned thing on either one. They're both awful, and so w…

Confluence is one of the best designed products I've ever worked with. Makes the web behave like a native editor, awesome semantic macros that let you put in warnings or collapsible sections in a few keystrokes, you can generate page source with scripts. Specifically regarding structure: - every page has breadcrumbs letting you navigate up to its parents - "child view" macro shows all children of this page automatica…

"Confluence is one of the best designed products I've ever worked with" is something I never thought I would hear. Building a wiki is admittedly a very hard problem, but you're the first person I'v seen, that loves Confluence.

Re: Stack Overflow for Teams

#160

Post by baq »

pm215 wrote: post #138
garrettgrimsley wrote: post #134

Earlier quoted context omitted.

Version control only answers "what happened?" not " why did this happen?"

"Why" is what commit messages are for (and also comments); quality of commit message is worth checking in code review while the details are still fresh in everybody's minds...

so i have to run blame just to figure out why something happened? i usually ask for explanations both in comments and commit messages.
Post reply on HN