Slashdot Mirror

← Back to Stories (view on slashdot.org)

Write the Docs Helps Create FLOSS Software Documentation (Video #2)

Posted by Roblimo on from the clear-documentation-makes-it-easier-to-use-the-software-you-wrote dept.

Say hello once again to David Smatlak, who works with Write the Docs -- a group that started some years back as Read the Docs.They have conferences in the U.S.and Europe, and Meetups in over a dozen cities. We ran a conversation with David Wednesday, but couldn't fit all he had to say into one video, so here he is again, with additional info that tags onto Wednesday's video.

14 comments

  1. Look at the sources by ls671 · · Score: 2

    Who needs documentation? Just look at the source code. I had enough difficulties writing it, you should experience the same reading it!

    Documentation is for sissies anyway...

    --
    Everything I write is lies, read between the lines.
    1. Re:Look at the sources by Anonymous Coward · · Score: 0

      Who needs documentation? Just look at the source code. I had enough difficulties writing it, you should experience the same reading it!

      Documentation is for sissies anyway...

      Proper documentation is a sign of software that works.

      If you can't explain how it works, it doesn't.

    2. Re:Look at the sources by Anonymous Coward · · Score: 0

      Proper documentation is a sign of software that works.

      If you can't explain how it works, it doesn't.

      This!

  2. Woosh... by ls671 · · Score: 1

    Woosh....

    --
    Everything I write is lies, read between the lines.
    1. Re:Woosh... by Anonymous Coward · · Score: 1

      Poe's Law. Too many people say "just look at the source code" and are serious.

  3. Is the UK exempt? by Anonymous Coward · · Score: 0

    They don't floss over there, do they?

    1. Re:Is the UK exempt? by ls671 · · Score: 0

      Constant effort is made to raise the use of dental floss in UK:

      http://www.colgate.com/en/us/o...

      https://upload.wikimedia.org/w...

      -Winston Churchill

      --
      Everything I write is lies, read between the lines.
  4. FLOSS? by Anonymous Coward · · Score: 0

    Wtf?

    Is that the best we can come up with?

    I'm sure we can add more letters to that acronym until no one has any idea what it means anymore.

    TRY HARDER!

  5. ftfy by Anonymous Coward · · Score: 0

    but couldn't fit all he had to say into one video, nor indeed all of David himself, so here he is again, with additional info

    FTFY

    1. Re:ftfy by Anonymous Coward · · Score: 0

      "That man has no neck!"

      FWIW, I've been writing Technical Documentation for over three decades; much of that time was DOE related. (Hey, a "Procedure" in DOE terms is a horrible thing. So if you want to describe a simple process, _don't_ call it a "Procedure". I coined the term "OpNotes" for "Operations Notes", in 1992. We reduced the number of required Procedures to 13 at our Facility; and they met the requirement that if not properly followed, personal injury or >$10K in damage could occur. For those Procedures, Biannual Review and Annual Training, with Records kept, are required. All the rest became OpNotes, which just required Initials and a date for when it was read. The DOE Inspector was surprised; with reflection, he thought that it was a terrific idea. He hated DOE/NRC Procedures as much as I did.)

      I have no idea why this Video was even posted. I read the Transcript, (Sorry, I don't do Flash.), and it was entirely lacking in _any_ content. People get together to write Documentation for FLOSS. That's it. Nothing new, nothing about the Pyramid Approach vs. Flat, nothing about comprehension levels, nothing about using Basic English, or HyperTexting.
      Nothing about References, or Indexing, or Edition Control. (Not _Version_ Control; that's entirely different.)
      Since this will be the _only_ response that actually deals with the Subject... Dammit Timmy!
      And please, no more NoNeck.

    2. Re:ftfy by Anonymous Coward · · Score: 0

      I'm just worried about the guy more than anything.

      But yeah not exactly an exciting or promising concept.

  6. Flash video by schamarty · · Score: 1

    Should /. be marking flash videos explicitly? Do people still use Flash -- at least the /. crowd?