Read the manual or documentation - Oh really ? How will that help ?

[Ali Gordon]

I wonder why people even produce documentation for a software ? Why not present it in Klingon instead. Here is a sampler
for git-push docs

git-push(1) Manual Page
NAME
git-push - Update remote refs along with associated objects

How about saying it like this instead -

git-push - Upload changes from your local repository into a remote repository

Looks like some people just love S&M, even in their work. With documentation like this, how is
one supposed to even learn something ? Sure, there are beginner books. But, how do the
authors themselves understand such cryptic stuff ? and...how do I learn the advanced stuff from
the "docs" with this kind of sadistic stuff ?

Look at the photo in my link to see what smarties have to say to us lesser mortals -

Abusive linus torvalds

[Bert Bates]

Hi Ali,

Well this topic is near and dear to our hearts. This is why Kathy started Javaranch in the first place, and why we write our books the way we do. To try to counteract this style of documentation and angry interaction.

[fred rosenberger]

"remote refs" - referees? I guess those would be the ones up in the control room, watching the game and doing the instant replay calls?


My peeve is when someone uses a TLA without explaining what it is...Oh...yeah...it's a three letter acronym for "Three Letter Acronym". And lets not forget about XTLAs...eXtended Three Letter Acronyms.

Of course, I also hate it when someone uses a term, the puts the acronym after it, but then NEVER USES THE TERM AGAIN.

[chris webster]

Think like a git may help you here. At least until "Head First Git" comes along...

[Ali Gordon]

@Bert @Fred @Chris - I like you. I like Bert books. It is a, very nice to have meet you all. I hope I can make books like Bert someday.
I want to make a technologies access to everyone.

[Rick Umali]

chris webster wrote:Think like a git may help you here. At least until "Head First Git" comes along...

Git certainly has a bad rap when it comes to "ease of learning." The manual pages for Git's individual commands are not ideal for learning the system.

Git's documentation does include a tutorial (man gittutorial, or git help gittutorial), inside of which point to some more entry-level documentation. It's still not perfect, however, as the documentation can quickly lapse into a discussion of internals. Check this URL for the Git tutorial.

https://code.google.com/p/git-core/source/browse/Documentation/gittutorial.txt

Some people (including myself) are trying to come up with book-worthy "tutorials" on Git, but it takes time!

[Frank Silbermann]

Bert Bates wrote:Hi Ali,

Well this topic is near and dear to our hearts. This is why Kathy started Javaranch in the first place, and why we write our books the way we do. To try to counteract this style of documentation and angry interaction.

Yes, but how does one understand the existence of people who write like that? Would be be solved by providing everyone with a small simple document called, say, rules for writing? Or is it a kind of autistic inability to empathize with readers -- an inability to distinguish which facts the reader is / is not likely to know?

[Hauke Ingmar Schmidt]

Ali Gordon wrote:I wonder why people even produce documentation for a software ? Why not present it in Klingon instead. Here is a sampler
for git-push docs

git-push(1) Manual Page

IMHO you searched for the wrong documentation in the first place. Ignore man pages as an end user. man pages are ... everything and nothing. At least you can't expect to find structured introductions into topics for different grades of experience there.

"man was great for its time. But that time has long passed." Written 1992, from the Unix Haters Handbook. While that might be a little bit polemic, man simply is not the tool most people need. It is the kind of documentation for people who think they need no documentation, just notes. Might work with a certain degree of experience with a certain piece of software.

[Bear Bibeault]

Frank Silbermann wrote:but how does one understand the existence of people who write like that?

Back when I was still living at home, my stepdad re-piped the entire hot water heating system to add six zones to the house (so that each zone could have its own thermostat) in place of the original single zone. The result looked like some sort of steampunk dream of pipes and valves.

When I marveled at its complexity, he said "It's easy. Anyone could do it."

Ummm, no.

The problem with many technical books is that they are generally written by experts, and it takes a lot of effort (and talent) for experts to remember that what comes easy to them does not come easy to everyone else. Many don't even grok that there is such a disconnect. And even for those of us that do, it's hard work to write in an accessible manner -- especially when writing about more advanced concepts.

I'm not making excuses for bad authors -- just pointing out that good writing may not be a easy as it might seem.

[Frank Silbermann]

Bear Bibeault wrote: I'm not making excuses for bad authors -- just pointing out that good writing may not be a easy as it might seem.

I agree that good writing is difficult, but it doesn't seem to me any more difficult than writing self-documenting code. But I guess most developers can't be bothered to do that, either -- even at the level of choosing identifiers. (For example, is investmentBookValue the value of a book about investing, or is it the book-value of an investment? Maybe it should have been written either as investment_bookValue or as investmentBook_value.)

[Jeanne Boyarsky]

Frank Silbermann wrote: Would be be solved by providing everyone with a small simple document called, say, rules for writing?

It's not that easy. Knowing a rule and applying it are two different skills.