/dev/chat

@FaheemMitha Documentation should not be generated from comments. Comments in code is for giving clarification to code, and extracting them would render them void of the context that they belong in.

Faheem Mitha

I suppose it depends if you are going with a full blown literate programming approach.

But mostly people write comments if something is unclear/obscure. And throw in the occasional docstring.

@Kusalananda I agree, unless the literate programming model is being used.

Though I don't know how that works, never having used it.

Michael Homer

It would be a peculiarly stupid autogenerator that took all the comments for documentation

Kusalananda

8:58 AM

Literal programming is not just "comments in code" though.

Faheem Mitha

@MichaelHomer Hard to know what comments to take without more information/instruction.

@Kusalananda I'm sure it isn't.

@MichaelHomer Also, computers are not known for their intelligence.

Michael Homer

javadoc and equivalents have been doing that for some time, even without going full literate-programming

Fabby

@Kusalananda Hey, this was 30 years ago... I Woudln't do that today any more...

@MichaelHomer It wasn't: it had directives to go into the help system and manual and directives to go into the manual only.

It worked for a small team (Just 5 devs maximum)

Kusalananda

Java doc etc. is just a way to insert documentation into code. That's basically a decision to keep the documentation close to the code it's documenting, nothing else. Again, it's different from comments in code (i.e. the purpose of the text is different).

Stephen Kitt

I find literate programming very useful for documenting why the code is as it is (as well as for structuring code). It doesn’t help much with writing docs for how to use the abstractions provided by the code.

And people writing code tend to not be that great at documenting how to use it :-/.

IME the best approach to getting good documentation and APIs, is to write the documentation first, then write the interfaces, then write the tests, and last, write the implementation.

Michael Homer

9:07 AM

javadoc is nonetheless pretty clearly comments, which is a syntactic class

Fabby

@StephenKitt :D :D :D True. I have some stories to tell on that one...

@StephenKitt Starred!

Faheem Mitha

The best user documentation would probably be that written by the users. But it's hard to get users to write documentation. Once they know how to use it, they're not interested any more.

Michael Homer

Good technical writing is a skill and one not generally possessed by the end users either

Faheem Mitha

@MichaelHomer Well, let's say end users who are technical.

It's not that much of a reach for programming stuff, at any rate.

Michael Homer

Who are technical writers, perhaps, though I think some distance helps

Faheem Mitha

9:12 AM

For example, Debian bug reports tend to be quite good. Why? Because Debian users are technical.

@MichaelHomer Most programmers, and even sysadmins, do a fair amount of writing, one way of the other. If only in reports.

And that assumes they haven't gone to the usual liberal arts education thing, where they have to write essays and stuff. Though that might be more an American thing.

Michael Homer

That idea is why so much documentation is so terrible

Faheem Mitha

Even a good high school education can teach one a lot.

@MichaelHomer What idea?

Michael Homer

Just hire actual technical writers

Faheem Mitha

@MichaelHomer What is the definition of a technical writer?

Stephen Kitt

@MichaelHomer agreed, I work with technical writes quite often and they have a very specific job which is hard for most people to do

Faheem Mitha

9:16 AM

Someone who only writes technical documentation?

Stephen Kitt

@FaheemMitha someone who makes a piece of software understandable for users

That involves knowing what users want to do, understanding enough of the system to be able to massage the developers’ explanations and ignore the stuff they care about which doesn’t matter to the user...

Faheem Mitha

@StephenKitt Ah. Well, that could be anyone. The writer of the software, an end user. Anyone with the technical and "literary" skills.

Michael Homer

Technical writer

A technical writer is a professional information communicator whose task is to transfer information (knowledge) between two or more parties, through any medium that best facilitates the transfer and comprehension of the information. Technical writers research and create information through a variety of delivery mediums (electronic, printed, audio-visual and even touch). Example types of information include online help, manuals, white papers, design specifications, project plans, software test plans, etc. With the rise of e-learning, technical writers are increasingly becoming involved with creating...

Stephen Kitt

And also understand how the user is liable to misunderstand the system and address that.

Faheem Mitha

I think the major requirement is actually wanting to do it.

Mostly people don't want to write documentation.

Michael Homer

9:17 AM

@FaheemMitha No.

Stephen Kitt

@FaheemMitha that’s what many people think, but IME it doesn’t have much to do with willpower.

It’s mostly about empathy.

Michael Homer

@FaheemMitha That is the idea I was talking about, and it's exactly the problem

Faheem Mitha

@StephenKitt People don't want to take the time, because it's not interesting to them.

@MichaelHomer Not following.

Stephen Kitt

@FaheemMitha and I’m saying it has nothing to do with taking the time.

Faheem Mitha

I've actually seen this in action myself. Start talking about documentation in a tech forum, and people's eyes glaze over.

@StephenKitt It doesn't?

Stephen Kitt

9:19 AM

@FaheemMitha no. Spending time on docs won’t make you a technical writer.

My rep here says I write reasonably good explanations, and yet I’m miles away from what our technical writers do at Red Hat.

Faheem Mitha

@StephenKitt I don't think it's that hard. With all respect to people who do it professionally.

@StephenKitt I find that hard to believe.

Stephen Kitt

@FaheemMitha just like any job you haven’t tried.

2

Faheem Mitha

Are you saying you couldn't write technical documentation?

@StephenKitt I've written technical documentation. What makes you think I haven't?

Stephen Kitt

Technical writers don’t write technical documentation.

Faheem Mitha

@StephenKitt They don't? Sorry, I'm getting lost.

Stephen Kitt

9:21 AM

@FaheemMitha they write documentation for whoever the target audience is. In most companies which pay for technical writing, that’s end users; end users don’t care much for what I think of as technical documentation.

Faheem Mitha

@StephenKitt Perhaps we mean different things when we say technical documentation.

I mean documentation about technical things. Perhaps you think I mean documentation that is itself very technical.

Stephen Kitt

@FaheemMitha have you ever been paid as a technical writer?

@FaheemMitha OK, I meant the latter.

Faheem Mitha

Like those software manuals that nobody can understand because they assume an intimate and expert knowledge of the software. Which is, frankly, maddening. Though I know such people do mean well.

And some documentation is better than none.

@StephenKitt No, I've never had that job title. Though I've certainly written documentation. And I don't think it's as hard as you're making it sound. Of course, it's not trivial either.

But really, I'm thinking more about stuff like manuals for a software library. Not something like MS Word. Which I agree is not really the same sort of thing.

Anyway...

Michael Homer

The "end user" of Microsoft's C# documentation and the end user of Microsoft's Word documentation are quite different audiences

Still tech writers composing it, though

Stephen Kitt

@FaheemMitha you’re saying anyone can do it, I’m saying that not anyone can do it; I’m not saying it’s outlandlishly difficult. However most people who think they can write docs, write poor docs.

Faheem Mitha

9:26 AM

@StephenKitt No, I'm definitely not saying anyone can do it. Sorry if I gave that impression.

But it doesn't require an "expert" either. Whatever that might be.

For example, the GNU documentation is generally good. Why? Not because the authors were super-talented technical writers, but because the project historically considered documentation important, possibly taking their lead from Richard Stallman, and fostered a culture that cared about such things.

Often technical documentation is very poor. E.g. the R help pages are ridiculous. (I don't mean to pick on R, it's just an example that comes to mind.)

And it's because they are not particularly thinking of the user side of the picture.

And the R devs are not receptive to constructive criticism. I did try once, I think. Perhaps I didn't do a good job of expressing myself.

(Sorry, I don't mean to ramble.)

Jesse_b

2:10 PM

heeeeeellllllllllloooooooooooo world || true

Stephen Kitt

Leeeeeeeeeeeeeeeeeeeroooooooooooooooooooooooyyyyyyyyyyyyyyyyyyyyyyyyyy Jenkins!

Jesse_b

=)

Ungeheuer

3:59 PM

@Fabby thanks for the pointers. I might end up doing that.

I also comment classes with a description of what their objective is and how they achieve it. Every method/function has comments describing what it does, why, parameters, returned values. I also comment unclear parts of methods/functions.

Shit is about to get real in the office.

We have a ping pong table, and yesterday me and a buddy were gonna chill for a couple minutes and play. There was no ping pong ball though.

Right now a couple cybersecurity interns are playing ping pong. The little bastards have been taking the ping pong ball with them when they finish playing....not sure how to get my revenge....

Jeff Schaller

@Ungeheuer tvtropes.org/pmwiki/pmwiki.php/Main/ScrewThisImOuttaHere

@Ungeheuer perhaps they feel like there's not enough ping-pong balls around, so you could fill their cube(s) with a few packs of these:

amazon.com/Sportly-Beer-Pong-Balls-38mm/dp/B01AH133KU

aderchox

5:02 PM

Hi

Is there a way I can both get the output of a non-terminating command and use & after it?

Jesse_b

@aderchox What do you mean non-terminating

aderchox

@Jesse_b for example when you run a server

Jesse_b

Well when you put something in the background you do get it's output by default

$ for ((i=0;i<5;i++)); do echo $i; done &
[1] 49521
0
1
2
3
4
[1]+  Done                    for ((i=0; i<5; i++))
do
    echo $i;
done

aderchox

I want something like this, but it's not working:

jupyter notebook > temp &; cat temp | chrome

not exactly this of course.

Jesse_b

jupyter notebook | tee temp &

aderchox

5:23 PM

@Jesse_b thank you but after running this command temp is an empty file

Jesse_b

does jupyter notebook produce output on stdout or stderr?

aderchox

@Jesse_b Oh thanks!

Fabby

5:52 PM

@JeffSchaller You're evil... But funny as hell! :-)

CC @Ungeheuer I agree with Jeff: fill their cubicles with ping pong balls or if that'll be frowned upon, at least their unlocked drawers, shelves, chair, ...

They're SecOps, right? They should have locked them anyway...

OTOH: More votes needed!

(if you get the joke)

Ungeheuer

6:06 PM

@Fabby is the point that the FSF's efforts are horribly and terribly confused?

@Fabby Can't do the cubes because they got all the interns in this giant rectangle cube in the warehouse. Gotta see if they have desks with drawers.

Maybe some 2x4, build a rectangle around their computers and monitors, fill with ping pong balls

Tim

6:27 PM

@StephenKitt I was wondering how you write the documentation, any standard to follow, or just personal style? What-driven development is doc->interface->test->implementation called?

Fabby

@Ungeheuer They've been at it for 30 years and haven't released anything.

Tim

Thanks. I am learning Monad by reading some basic category theory these days. Categories for the Working Mathematcian, by Mac Lane

To study Scala, which will help the most, learning Haskell or SML or OCaml?

Faheem Mitha

@Fabby I think the idea is to advertise whatever it is, and not poke fun at it.

Tim

The OO part of Scala is a "better Java". I assume Java is not adequate for studying Scala's OO part. Which language will be helpful then?

Ungeheuer

@Fabby wait...WHAT?

I'm not familiar with them at all, probably heard of them at some point for sure.

Fabby

6:53 PM

@FaheemMitha SOHF? (Sense Of Humour Failure?)

Faheem Mitha

@Fabby Humor is fine, in its place. I'm not sure that's its place.

Fabby

@Ungeheuer The GNU Utilities is what started the modern free/libfre software.

They just never had a kernel to run it on and Linux became the De Facto standard (together with BSD)

GNU HURD is the FSF's take on a Kernel: much more ambitious than the Linux and BSD one, but yes: nothing has been released yet.

@FaheemMitha It won't make it to the actual advertisement system anyway and I know I've made 5 people happier so far.

0:-)

Ah, and apparently one person unhappy! (1 downvote)

Tim

7:08 PM

Michael Homer

8:25 PM

@Tim I really don't think that will be useful for programming

@Tim Presumably learning Scala will help the most for studying Scala.

Tim

8:41 PM

@MichaelHomer I can't understand the explanations of monad in terms of the functional languages. They are supposedly easier to understand than the categorical definition, but I haven't managed to see that.

@MichaelHomer Scala borrows a lot of features from several languages of different paradigms and even within the same FP paradigm. I guess that makes it harder to understand well than some languages it borrows from, when one doesn't feel easy to separate and group the features.

Ungeheuer

9:46 PM

The RHEL7 NFS guide access.redhat.com/documentation/en-us/red_hat_enterprise_linux/… mentions /etc/sysconfig/nfs not /etc/nfs.conf, however, the nfs manpage doesn't make reference the former, and there exists a manpage for the latter file. Which one should I be using? They are both configuration files for the server and configure the same things. I don't think it matters in terms of functionality, but I care about best practice.

Ungeheuer

9:58 PM

nfs.conf is also mentioned in rpc.gssd's manpage

Transcript for