Please create an account to participate in the Slashdot moderation system

 



Forgot your password?
typodupeerror
×

Comment Re:The term "documentation" is subjective (Score 1) 188

Are you sure you're really receiver-focused when you write all that stuff? Most people don't want to read that much text to use, say a configuration parser. If it takes people 10 hours to dig through your documentation and 1 hour to actually write the code, you're probably not doing it right. Sometimes less is more.

In the case of my configuration-file parser, a new user just needs to open the Getting Started manual and read two short chapters: Overview of Config4* syntax and Overview of the Config4* API. I would be surprised if doing that would take more than 30 minutes. And having done that, it would then take the new user about 5 minutes to write working code.

Comment The term "documentation" is subjective (Score 5, Interesting) 188

There is an old joke: "The definition of promiscuous is somebody who has more sex than you do". From reading TFA and some of the comments on slashdot, I get the feeling that the definition of documentation is equally subjective and self-serving for developers. Some developers think that writing documentation means adding comments to code. Others feel it involves writing Javadoc/Doxygen-style comments at the start of every class and method, and then generating HTML from that. Yet others feel that documentation hasn't been written unless it involves an architectural description.

When I am working on my own open-source projects, I feel that documentation isn't complete until I have written a few hundred pages of text that aim to be cover most/all of the following: (1) API reference guide, (2) programming tutorial, (3) user guide, (4) architectural guide, and (5) suggestions for "future work" that I hope other people will volunteer to do. Yes, I recognise that I am a bit extreme in the amount of effort I put into writing documentation. However, it does enable me to elaborate on the thesis of TFA: attempting to write such a comprehensive amount of documentation often highlights not just coding bugs, but also architectural flaws. This causes me to work in an iterative manner. I implement a first draft version of the code. Then I start documenting it, and when I encounter a part of the software that is difficult to explain, I realise that I need to re-architect the code base a bit. So I do that, and then get back to writing documentation, which causes me to notice another difficult-to-explain issue with the code. Working in this manner is slow, and I suspect it wouldn't work in a business with time-to-market pressures, but I find it gives excellent results in my own, non-time-pressured open-source projects. I touched on this issue in the documentation for one of my open-source projects.

Comment Re:No Carrier (Score 1) 462

I stopped for about a year and a half and recovered my health. However, as time went on my social and work circle as well as my family were too difficult to be around since they all are either wine snobs, after work happy hour drinkers, or simply unwilling to not drink around me. I didn't feel the desire to drink as strongly as before, but I felt left out of pretty much everything they were doing.

I don't drink alcohol because I have some sort of allergy or intolerance to it. As a teenager and young adult, I tried socialising with friends in bars. They would drink alcohol while I drank a soda or water. Eventually I gave up trying to socialise in such places. It boiled down to something somebody one said to me: "Those who are sober don't make good company for those who aren't. And vice versa."

Comment Re:Why I don't like Creative Commons (Score 1) 210

I also have concerns about the Creative Commons set of licenses.

First, four of the six Creative Commons licenses are not "open source" since they prohibit modification and/or commercial use. There is nothing wrong with that per se; my gripe is that Creative Commons seem happy to let people assume that their licenses are open source.

Second, Creative Commons do not provide txt/Word/RTF/LaTeX/whatever versions of their licenses that you can download and embed into a book you are writing. Instead, the copyright page of your book is supposed to just tell readers that they can find the text of the license on a website or by writing to a specific postal address. So what happens if: (1) the Creative Commons organisation's postal address changes, and (2) they forget to renew their domain name and a cyber squatter buys it and holds it to ransom for millions of dollars? (More realistically, what happens if in, say, 20 years time, the Creative Commons organisation goes bankrupt and shuts down operations.) Now the license page of your book tells readers that it is licensed under terms that they cannot verify.

Third, the Creative Commons have gone through 5 versions of licenses (1.0, 2.0, 2.1, 2.5 and 3.0) in just over 4 years and (as far as I know) there is no forwards or backwards compatibility between the different versions.

Comment Re:Why was the contract unsealed? (Score 5, Informative) 130

"Angered at Righthaven’s behavior, a Las Vegas federal judge unsealed the company’s heretofore confidential agreement [...]"

Not that I'm complaining, but... what did Righthaven do to anger the judge? Were their lawyers being dicks? Was the contract itself what angered the judge? Truly, I'd like to know.

You can find the answer to your question in the final two paragraphs of the first link in the /. summary. I'd like to quote those two paragraphs for your convenience. But then, according to the thrust of the article, I might be sued for copyright infringement.

Comment Re:I don't know what to think (Score 1) 222

I would hope that everyone would find something even more important to do during their last weeks than fix gnome bugs.

The article written by Adrian Hands' son states, "Adrian Hands loved free software / open source." This means Mr Hands spent the last few weeks of his life working on something he loved, and which happened to be of benefit to others. Off hand, I can't think of a better, more important way for a person to spend the last few weeks of their life. Sure, you might say that he could have spent some time talking to loved ones. But who says he didn't do that too?

Comment Re:it was (Score 1) 452

you know that it was as such, when the perpetrators of the case first merrily publish blog posts titled 'how to take revenge on him through legal system', telling how disgruntled women should abuse the legal system to exact revenge on males, and then delete the post once the internet community becomes aware of it.

That is untrue, and the newspaper article you cited when asked for a source is incorrect. The woman did write a blog article that offered advice on how to get revenge, but the blog article did not suggest using (or abusing) the legal system to do so.

Read an English translation of the blog article if you want to check.

Comment Re:Sorry, no "dirty tricks" campaign here... (Score 1) 1060

From the provided link:

Earlier this year, Sarah is reported to have posted a telling entry on her website, which she has since removed. But a copy has been retrieved and widely circulated on the internet. Entitled ‘7 Steps to Legal Revenge’, it explains how women can use courts to get their own back on unfaithful lovers. Step 7 says: ‘Go to it and keep your goal in sight. Make sure your victim suffers just as you did.’ (The highlighting of text is Sarah’s own.)

The newspaper article was very misleading in its characterisation of the blog posting. The only occurrence of "legal" (or any related word) was in the title of the blog article, and that should be read as "7 steps to taking revenge without breaking the law" rather than as "7 steps to taking revenge by talking legal action". The blog posting did not suggest using the courts to get revenge.

The very first step in the blog article stated: "It is almost always better to forgive than to avenge".

Steps 3 and 7 in the blog article suggest that the form of revenge you take should be similar to and in proportion to how you feel you have been wronged.

To characterise the blog article as a recipe for how to bring false accusations of rape against a person is incorrect.

For anyone who is interested, here is a translation of the blog article.

It is clear to me that inaccuracies in the media and on the Internet are demonising not just the accused but also (at least one of) his accusers.

Comment Re:It's the other way around actually.. (Score 1) 1020

Maybe I'm missing something, but I don't see how the Seven step model for legal revenge blog article supports the claim that she "has been outspoken about how women should use rape accusations to destroy men".

First, the blog article does not mention rape accusations at all.

Second, the blog article advises that, "It is almost always better to forgive than to revenge".

Third, the blog article advises that if you do decide to revenge rather than forgive, then the revenge should not be disproportionately excessive.

Can you elaborate on how you think this blog article supports the claim?

Comment Re:The source of the problem (Score 1) 542

Holy fuck is it annoying to completely rewrite document after document produced by a bunch of slackers who think because they know how to ping something that means they can be practically nonfunctional at everything else including such basic things as language.

That reminds me of an old piece of graffiti: I used to want to be an engineer. Now I are one.

Comment Re:Hunger Strike? (Score 1) 151

Actually, Gandhi made several hunger-strikes, but they all occurred only after he was a hugely popular leader- which meant that the possibility of his death, brought massive pressure over the ruling British Government who would have to deal with anarchic rage riots that could break out in the population.

True. But Gandhi also trained some (I think a few dozen) of his followers in his tactics, and sent them off to various villages to carry his message. Typically, such a follower would work hard to become a respected member of the village. Later, if a serious disputes arose in the village, then the person might go on hunger strike until the dispute was resolved. According to one of Gandhi's biographies, such hunger strikes were successful in ending disputes, at least in some cases.

I think this shows that a person who is respected nationally can go on hunger strike and have a national impact, while a person who is respected more locally can go on a hunger strike and have a local impact.

Whether locally, nationally or internationally known, a hunger strike is much more likely to be effective if there is widespread publicity about it. The fact that the Chinese people on hunger strike against Google have gotten international exposure will certainly help their chances of success.

Slashdot Top Deals

All the simple programs have been written.

Working...