81–90 of 97 posts
Related to this: understanding the various types of documentation, and using them all appropriately. I highly recommend Daniele Procida's talk about this, [0] and the accompanying web page [1]. He gives a useful taxonomy of the 4 kinds of documentation. Through the power of Unicode: ┌──────────────────────────┬─────────────────────────┐ /\ │ Tutorials │ How-to Guide │ || Practical │ (Learning-oriented) │ (Problem-ori…
I think the author is missing a key part of why developers often don't like writing documentation but do like answering questions: replacement value. A developer's compensation is based upon their perceived value (how much it seems like they are needed) and replacement value (how much would it cost to replace them). A developer that answers questions gets a reputation for helpfulness - this increases their perceived…
Fair point, but I really doubt that is really a key component, specially given how fruitfull the developer market is. Very few people stays in the same company for more than 3-4 years in my experience. So, if you're just going to stay a couple years, you probably don't care about your replacement value. I'd say that, in general, people don't like writing docs or answering to people. But if someone asks you a question…
Earlier quoted context omitted.
And that developer gets fatigued by constantly having to tell others to RTFM, because the documentation is up to date and comprehensive, he took his damn well time to make it so, if they just also took their time to read it, but instead they always ask him anyways or he has to point everything out and at a certain point they just don't care anymore.
It's very true. I think in reality it tends to be a mix—sometimes documentation goes stale, and sometimes people don't even bother reading it regardless of whether or not it's stale. Another large problem is developers not knowing what they're looking for. Documentation tends to solve the "how I do use this" question and not the "do we already have a solution for this" question. I'm still not sure how to solve the pr…
The reality is, this sort of behaviour isn't penalised or shamed. Said developer got called out in a meeting with many others present and didn't even appear to feel embarrassment or apologise. Makes it tough to get people to write and take pride in documentation when that sort of thing happens.
I found organizing and finding documentation to be a huge problem ten years ago, not so much now with wikis having decent search. The biggest problem remaining is that it's simply hard to write good documentation, much harder than providing ad-hoc help in person or over Slack. The reason is that every time you provide an ad-hoc explanation of how something works, you have a concrete context: a person, what they're tr…
I tend to see docs and interactive QA as complimentary. If you can answer questions by linking to documentation it saves a lot of time.
I think the author is missing a key part of why developers often don't like writing documentation but do like answering questions: replacement value. A developer's compensation is based upon their perceived value (how much it seems like they are needed) and replacement value (how much would it cost to replace them). A developer that answers questions gets a reputation for helpfulness - this increases their perceived…
Fair point, but I really doubt that is really a key component, specially given how fruitfull the developer market is. Very few people stays in the same company for more than 3-4 years in my experience. So, if you're just going to stay a couple years, you probably don't care about your replacement value. I'd say that, in general, people don't like writing docs or answering to people. But if someone asks you a question…
However even if you take out the replaceability I still think that there's a relatively limited upside.
Thus you're left with conscience or a sense of professional pride as motivators to write docs.
Earlier quoted context omitted.
Conjecture: almost every belief that your wiki needs support for ACLs and needs to be moderated (for any reason other than spam) is a belief that's wrong from the start. (And it should be a criminal offense the way that GitHub and GitLab to have corrupted the word "wiki" to be understood to include PR- and review-based workflows centered around big collections of offline source files—the very practice that the wiki w…
GitHub and GitLab have a wiki feature that is a sort of crappy wiki with no merge requests. The problem is that wikis can’t be globally editable without license events so in order to edit the wiki you need permissions on the project. The PR flow is for the non-wiki where there’s just files in a repo that only active project users can edit but anyone can fork and PR. So it’s a lot easier administratively than trying t…
What does this mean?
> If there was a decent wiki product
Like Mediawiki.
Earlier quoted context omitted.
It's very true. I think in reality it tends to be a mix—sometimes documentation goes stale, and sometimes people don't even bother reading it regardless of whether or not it's stale. Another large problem is developers not knowing what they're looking for. Documentation tends to solve the "how I do use this" question and not the "do we already have a solution for this" question. I'm still not sure how to solve the pr…
Poor reading speeds and skills are a huge problem. I've wirken with even supposedly senior developers who will not read the user guide for some complex piece of software before trying to use it or even worse, mouthing off about how it doesn't have feature X so task Y will be too difficult so we should switch to an alternative! The user guide in this case was comprehensive and fresh. The reality is, this sort of behav…
I would not want to work with anyone who thinks public shaming is right or even effective. It kills morale, makes people fear asking questions, creates a low-trust environment, and frankly is just plain rude.
Earlier quoted context omitted.
Fair point, but I really doubt that is really a key component, specially given how fruitfull the developer market is. Very few people stays in the same company for more than 3-4 years in my experience. So, if you're just going to stay a couple years, you probably don't care about your replacement value. I'd say that, in general, people don't like writing docs or answering to people. But if someone asks you a question…
You're right - I think a lot of people don't care. However even if you take out the replaceability I still think that there's a relatively limited upside. Thus you're left with conscience or a sense of professional pride as motivators to write docs.
Earlier quoted context omitted.
Poor reading speeds and skills are a huge problem. I've wirken with even supposedly senior developers who will not read the user guide for some complex piece of software before trying to use it or even worse, mouthing off about how it doesn't have feature X so task Y will be too difficult so we should switch to an alternative! The user guide in this case was comprehensive and fresh. The reality is, this sort of behav…
I don't disagree that someone not reading the user guide is annoying, but I vehemently disagree than penalizing or shaming is appropriate in any professional workplace. I would not want to work with anyone who thinks public shaming is right or even effective. It kills morale, makes people fear asking questions, creates a low-trust environment, and frankly is just plain rude.
In the noted case there was no overt penalizing (at least that we heard about) nor was there shaming (the person was apparently "unshameable"). Therefore your post falls short of it's target.
That said, in general, I agree with every word you said. I especially like the "frankly [it] is just plain rude." - good manners (etiquette) can make a world of difference in a workplace but have largely fallen by the wayside in our culture.
Earlier quoted context omitted.
I don't disagree that someone not reading the user guide is annoying, but I vehemently disagree than penalizing or shaming is appropriate in any professional workplace. I would not want to work with anyone who thinks public shaming is right or even effective. It kills morale, makes people fear asking questions, creates a low-trust environment, and frankly is just plain rude.
He said "Said developer got called out in a meeting with many others present and didn't even appear to feel embarrassment or apologise." In the noted case there was no overt penalizing (at least that we heard about) nor was there shaming (the person was apparently "unshameable"). Therefore your post falls short of it's target. That said, in general, I agree with every word you said. I especially like the "frankly [it…
I feel the best courses of action are to remind the developer privately and/or to make a general "remember to read the docs" statement to the whole team in the meeting.