Follow Slashdot blog updates by subscribing to our blog RSS feed

 


Forgot your password?
Close
typodupeerror
×
Programming

Eric Raymond Stumped By Documentation's 'Reproduction' Problem (ibiblio.org) 98

Posted by EditorDavid from the learning-by-examples dept.
Eric Raymond has been working on a tool called reposurgeon for editing version-control repository histories -- those "risky operations that version-control systems don't want to let you do." But this led to some interesting thoughts about documentation: "Why doesn't reposurgeon have easy introductory documentation" would normally have a simple answer: because the author, like all too many programmers, hates writing documentation, has never gotten very good at it, and will evade frantically when under pressure to try. But in my case none of that description is even slightly true. Like Donald Knuth, I consider writing good documentation an integral and enjoyable part of the art of software engineering. If you don't learn to do it well you are short-changing not just your users but yourself...

If you go looking for gdb intro documentation, you'll find it's also pretty terrible. Examples of a few basic commands is all they can do; you never get an entire worked example of using gdb to identify and fix a failure point. And why is this....? High-quality introductory software documentation depends on worked examples that are understandable and reproducible. If your software's problem domain features serious technical barriers to mounting and stuffing a gallery of reproducible examples, you have a problem that even great willingness and excellent writing skills can't fix.

Of course my punchline is that reposurgeon has this problem, and arguably an even worse example of it than gdb's. How would you make a worked example of a repository conversion that is both nontrivial and reproducible? What would that even look like...? Having identified the deep problem, I'd love to be able to say something revelatory and upbeat about how to solve it.... Unfortunately, at this point I am out of answers. Perhaps the regulars on my blog will come up with some interesting angle.
This discussion has been archived. No new comments can be posted.

Eric Raymond Stumped By Documentation's 'Reproduction' Problem More

Eric Raymond Stumped By Documentation's 'Reproduction' Problem

Comments Filter:

  • Lost me at 'esr'. (Score:4, Insightful)

    by Slartibartfast ( 3395 ) * <ken@nospAm.jots.org> on Sunday February 02, 2020 @06:52AM (#59681204) Homepage Journal

    Over the years, I have come to decide that esr has gone from a bet win (open-sourcing of Netscape, Cathedral and the Bazaar) to a net-negative: rambling screeds about being rich, about being poor (and how his fall was the government's fault), homosexuality, guns, etc., etc. I find I no longer much care what the self-important blowhard has to say about much of anything.

    • This is a religious feud for you types. I get it. . Nobody cares.

      Look up "ad hominem". And "logic".
      (Hint: If *Hitler* said it is usually dark at night, he'd still be right.)

      • Sorry, I have to agree with the GP. I followed ESR on G+ back when that was a thing and continual exposure to his trolling ways likewise cured me of thinking he was worth listening to.

        Further, the subject of this discussion is simply further evidence of same: he can't imagine what a useful example for his tool would be. Which raises the question, why does it exist? If there's a need for this tool, there should be ample examples. But he is managing to deflect attention from that by complaining about gdb. Rem

    • Re: (Score:3, Insightful)

      by account_deleted ( 4530225 )
      Comment removed based on user account deletion
    • In other words, he was right, but as his politics don't match your own, he becomes an unperson. Unpersons don't exist, therefore their views are invalid. Amirite?

      • Frankly, when people's politics leads me to act like idiots (claiming they are an ancient native american gender is a good example, claiming that they are a single person country is another), yes, it's a good reason to ignore them. Life are too short to give attention to every idiot out there.

    • The entire point behind the OSI was to water down Free Software into something more business friendly by downplaying and denegrating various freedoms advocated by the FSF.

  • Supply and Demand (Score:5, Interesting)

    by syntap ( 242090 ) on Sunday February 02, 2020 @06:56AM (#59681212)

    As much as I like to document for my own development, on the macro scale I suppose the answer is because it is demanded neither by users nor developers.

    Humans evidently care more that something works and resources spent on development and improvement than info on how it got there, exceptions being for things that have physical risks to humans like space and medical applications.

    One of my earliest development mentors told me code is read many more times than it is written, so documentation either embedded in code or as a separate product is smart. That always stuck with me and were that taught along with the basics of what a loop is I think we'd have more.

    • Re:Supply and Demand (Score:5, Interesting)

      by Anonymous Coward on Sunday February 02, 2020 @08:11AM (#59681276)

      I think this is a key part of the problem, it's not that we don't need documentation, it's that it should only need to be minimal. If your software is sufficiently usable it shouldn't need much documentation.

      And this is really the problem, you can write a poorly usable piece of software, and heavily document it, or you can write an easily usable piece of software, and not have to document it. It's really upto the developer which they want to do.

      But I've noticed a really annoying recent trend; the trend of video documentation. Stop, just stop. I don't always have a headset to hand to quietly listen to a video without the whole office or wherever I'm working being annoyed by it. Your videos basically never have any kind of index mechanism to look up specific bits of documentation I need; I shouldn't have to watch a 2hr tedious video just to find the information I could find in less than a minute by clicking through a text based hyperlinked index.

      Good documentation is a talent in itself, creating 50 pages of documentation is often less effective than 5 pages of well thought out documentation making effective use of diagrams for example.

      So all in, the key to good documentation is this; keeping it as small as possible by using not just walls of text, but effective use of diagrams, infographics and such, and also by simply making sure your software is sufficiently usable that you don't need much documentation in the first place.

      • Re:Supply and Demand (Score:5, Insightful)

        by Kenneth Stephen ( 1950 ) on Sunday February 02, 2020 @09:03AM (#59681348) Journal

        I'll agree with most of what you say, but there is a common scenario where "sufficiently usable" doesn't cut it. This is when the person trying to use the software isn't a domain expert in the problem being solved by the software. For example, I don't know anything whatsoever about image layers, and alpha channels and whatnot: I simply want to be able to crop, and paste into / from images, but GIMP insists on speaking to me in those terms. I recognize the GIMP is a very popular tool, but the barrier of entry is very high for someone who has to use it once every few years. What would help is exactly the kind of documentation that walks me through the terms and how they apply to common scenarios.

        I picked on GIMP here, but I don't want convey the impression that it is bad or the worst or anything like that. The problem is pervasive. The field of software is so broad these days, that it is almost a given that to complete a large project, you will have to casually use some tools where you are not going to be an expert, and will have no intention of being an expert (because that is not your primary area of focus / skill). Documentation really should be better.

        • Yeah - thorough documentation is nice when you're looking to become an expert - but there does seen to be a shortage of good, concise quick-start guides. Especially integrated "first party" ones, which is where they would be most helpful. I've also noticed a dearth of illustrations in such guides, which I think often does them a great disservice - for example an exploded image of stacked old-school transparencies with varying opacity would explain the essential points of the layer and transparency system

        • I tried to use GIMP several times.
          I found it unbelievable that you had no tool to make a straight line to "crop" and area for further manipulation or cut/copy + paste something.
          A /. poster pointed out you have to use ctrl (or alt) while click+dragging ... that might be hidden somewhere in the docs ... that was 15 years ago or so ... never even tried to use GIMP again (actually my use cases are extremely limited for picture manipulation anyway). I found that retarded ...

        • I think that's more about using the wrong tool for the job. I hate it when GIMP is recommended to ordinary people for trivial day-to-day picture editing tasks, as it was not even remotely designed for that.

          Documentation isn't really the issue. Nobody wants to use a "second-rate" piece of software, so people always seek out the "best" program -- a huge, bloated, complex behemoth -- when a simpler, easier program would suffice. Hey, why are you using that piece of trash when we have GIMP? Why are you usin

      • Re: (Score:1)

        by Anonymous Coward

        >Good documentation is a talent in itself, creating 50 pages of documentation is often less effective than 5 pages of well thought out documentation making effective use of diagrams for example.

        And whether it's 5 pages or 50. "Chunking" is bullshit.

        If your documentation is online, provide a single chapter1.html or even an entirebook.html so that I can hit ^F foobar to find out how to Foo a Bar, or just lazily scroll through the whole thing in one sitting.

        1) Welcome to the Foobar 1000! *click* *wait

        • Re: (Score:2)

          by HiThere ( 15173 )

          Chunking is good, chunking is excellent, chunking is necessary....but not at the cost of rapid lookup.

          The problem with that list of links you listed was not that it was detailed, but that they were links to separate pages.

          OTOH, it's possible to run into situations where there is a memory constraint, and you can't hold it all in ram. For that a web browser is a bad idea, but info is a better choice...but only then, as they are difficult to navigate.

      • Amen to this. I refuse to watch video documentation. It runs too slow and requires that I bother my roommate with the audio. There are far too many people who think that it's a substitute for written docs, especially in the world of graphics programs; most fo the docs for two Blender add-ons I use regularly are video, and it drives me batty. Give me a written doc or GTFO.

      • > I shouldn't have to watch a 2hr tedious video just to find the information I could find in less than a minute by clicking through a text based hyperlinked index.

        Indeed. Video documentation SUCKS for one primary reason:

        * Find (via Ctrl-F / Command-F) completely fails to work.

        Having to manually "scrub" the video for that magic timestamp is a completely fucking waste of time for the viewer.

        People seem to be clueless that different mediums have different strengths.

        * Video is great for linear consumption.
        *

        • * Video is great for linear consumption.
          * Text is great for non-linear searching.

          In some tutorials, a topic builds on previous topics, and the author wants to ensure that the viewer has had time to understand preliminary topics before viewing a more advanced topic that builds on said preliminary topics. Some authors might find linear consumption superior to non-linear searching for ensuring this.

          • Some authors might find linear consumption superior to non-linear searching for ensuring this.
            Hence we ignore such authors ...

          • Re: (Score:2)

            by Megane ( 129182 )
            That's called a "training video", and should not be confused with documentation, especially by its creator.

    • "Humans evidently care more that something works and resources spent on development and improvement than info on how it got there, "

      Until you get run over by a truck, then they're fucked.

    • I think its more a case of effort expended.

      Most development is now "hack some stuff together until it works, and then fix and refactor it constantly".

      As a result, a lot of documentation is out of date the moment its written.

      If we ever went back to a "plan something", then build it and leave it along, then documentation doesn't only work well, but feels good to create as well.

  • Many hands make all task easy.

    • Might I disagree? We might assume that, but do take a look at any large technical mailing list or IRC channel The difficult or controversial parts are often neglected.

      • It was a play on words designed to stimulate conversation, though I was expecting the Mythical man-month or nine women paradox to show their faces humorously.

  • The problem is the tools probably don't match the complexity of the domain yet.

    Remember when test scripts used to be text documents ("do this, run that, check this"), with the odd picture thrown in? Now tests execute in fully-automated execution environments ("build server, deploy code, run integration 2000 tests with 10000 assertions, run load test, report...").

    For ESRs case, I'd expect ideal 'documentation' would be some sort of 'living document' which embeds virtual machine-like execution components with

  • I love writing documentation! (Score:5, Insightful)

    by AxisOfPleasure ( 5902864 ) on Sunday February 02, 2020 @07:31AM (#59681236)

    I love writing code, processes and putting systems together and I love writing the documentation that ensures people can use the things I put together. It's a genuine challenge to find the required empathy with your target audience. Docs complete the project properly, to finish the documentation, have it checked and confirmed means you can close down a project properly knowing you did it right.

    People think that avoiding writing docs will make them invaluable. I've worked for many managers who will make sure people who try that trick are the first to go when headcounts are cut simply for trying to hold a company to ransom. Writing docs means they will put up to go first but they can't accuse you of holding anyone or anything to ransom.

    Good documentation is also its own reward, it means you don't get a ton of people chasing you down trying to find out how the heck XYZ is supposed to work. So many of my colleagues complain about being bugged by people about something they've built 'cos their docs aren't good enough and they never improve them. Writing docs is a skill in itself, just like coding it needs plenty of practice. People read the docs and they either get it or they don't, and if they don't get it then I find out why and make time to fix the documentation much as I would the code and processes. Any time I find a process that I know others need to know about, I write some docs on it.

    Writing docs takes practice, it takes time but it's worth it as you don't have to worry about some 2 year project coming back and biting you in the ass.

  • Professional technical writers have methodologies for creating documentation, and they also have plenty of blogs. You can start by seeing what they have to say.

    People who don't like writing sometimes freeze up at a blank page. To get past this, just start writing any old explanation of your work, without worrying if it's good. You'll end up with a lot of garbage and some good stuff, but at least it didn't take long. Then go back and clean it up.

    I like to use the DITA methodology. You don't have to work w

  • Devs don't like to duplicate same thing twice: once as code and once as human readable imprecise documentation that won't even get you compile errors if you get things wrong. Also, it's added maintenance burden since it can get out of sync with newer iteration of code if project changes its structure but some parts of docs remain forgotten.

    • Re: (Score:1)

      by Anonymous Coward

      My boss likes to expound on how the code is the documentation, and comments aren't permitted in the code, and we will not have any documentation, yada yada.

      But yet, when push comes to shove, and he's confused about a third party library not working, he just keeps staring at their documentation instead of reading their code. He'll insist up and down for a week that, "no, that's not what the documentation says!"

      Me, I read the docs until something doesn't jive, then I read their code. More efficient use of my

      • My boss likes to expound on how the code is the documentation, and comments aren't permitted in the code, and we will not have any documentation, yada yada.

        Your boss is a fucking idiot, your project is doomed, and you should be actively looking for your next job.

        Code communicates to machines. Comments and documentation communicate to human beings. Anyone incapable of understanding the difference should never be allowed in the profession.

      • Ah, this must be the Uncle Bob I have heard the junior coders talking about!

      • Re: (Score:2)

        by jeremyp ( 130771 )

        The code tells you what the computer will do.

        The comments should tell you what the programmer was trying to make the computer do.

        If there is a discrepancy between the two, you have identified a bug.

  • > the author, like all too many programmers, hates writing documentation, has never gotten very good at it, and will evade frantically when under pressure to try.

        And that's pretty much why we have 'Agile' now. Run through the methodology and Agile is pretty much a reworking of the software development process where you toss out all the behaviours which require you to to act like a mature adult.

  • Documentation is usually too granular (Score:5, Interesting)

    by Dan East ( 318230 ) on Sunday February 02, 2020 @08:48AM (#59681318) Journal

    The problem is simple. Documentation is usually too granular, which makes sense because as developers we are taught to create small functions that do a specific thing. So the documentation we produce is extremely specific about one individual feature, parameter, switch, whatever, that does a specific thing.

    The problem is that the person using that functionality is almost always doing so in combination with many other things. An example might be command line switches for an app. Say there are 20 of them and each is described in detail. When they are used in combinations they may behave differently, or the use of 3 switches together requires a 4th to also be specified. Or you can't use two switches together. The permutations grow very quickly, and the documentation is seldom arranged in a way where those permutations can be understood as sets or groups.

    The reason places like Stack Overflow are popular (and typically very useful) is because it deals with actual usage of things. People pose questions, generally containing very specific examples and desired usages of something. Others reply with very specific examples showing a (usually) working solution. These questions and answers almost always deal with a specific permutation of things - specific parameters to a function, the use of multiple functions together, etc.

    Here's an example of how pure documentation fails us. Take a skilled developer who has never used or seen SQL before. Give them the reference manual for the SQL commands with no code samples. This documentation is absolutely thorough still, correct? It shows exactly how every command is structured, what it does, etc. How much difficulty would they have composing a typical modern non-trivial SQL statement? A great deal of difficulty. My point is that, since there are practically infinite combinations of how those commands can be combined, providing one or two code samples in the documentation doesn't begin to address the complexities one faces when combining commands together into more complex constructs.

    So the question is when is documentation just documentation, and when should it be a... knowledge base, a tutorial, a code repository, a training course, a FAQ, a boilerplate, a template...

    • Re:Documentation is usually too granular (Score:4, Interesting)

      by weilawei ( 897823 ) on Sunday February 02, 2020 @09:15AM (#59681380)

      That's why we have references and user guides.

      Or you could just figure out who wrote Commodore's manuals and hire them. That person(s) knew how to write for a real live human, but still provide all the fine detail on the fiddly bits. Those manuals are worth their weight in gold for those systems.

      • Those manuals are worth their weight in gold for those systems.

        As an aside, let me make it clear that I was being generously literal. I just weighed my copy of the C64 Programmer's Reference Guide at 595g. The spot price of gold according to Google is $51.16/g. That's $30,440.20.

        Now, that seems to me a fair price for them to have paid someone to make that manual, and I imagine that a lot more than $30k worth of benefit came of it.

    • The reason places like Stack Overflow are popular (and typically very useful) is because it deals with actual usage of things. People pose questions, generally containing very specific examples and desired usages of something. Others reply with very specific examples showing a (usually) working solution.

      The reason places like Stack Overflow are popular (and typically very useful) is that someone else does all the hard work of locating the information and creating a solution.

  • ESR is... (Score:4, Funny)

    by 110010001000 ( 697113 ) on Sunday February 02, 2020 @08:50AM (#59681322) Homepage Journal

    ....the programmer equivalent of Steven Seagal.

  • That state of cryptic parameters and commands, and separate man pages, is just as bad as those stupid "search" interfaces, that mimic CLIs and force you to play a losing game of Family Feud, yet are all the rage nowadays.

    Please write your software in a way that it is self-explaining. In every state it can be in. And telling you when it would lead you into situations you can't revert. No exceptions. (Ideally, make *everything* undoable... Yeah, I'm looking at you, Android and iOS!)

    And I don't mean explanatio

  • In the mid-1980's, I just hit the code. In the 1990's I changed my style to start with an outline in code comments. Today, I tend to begin with what it should look like, in layers. So work this all out in documentation because once I have a clear vision of the whole system, the coding comes along very quickly. It's figuring things out that takes the time. Granted, I make many revisions when I have time to do so -- but mostly to documentation and less now days to the actual code. It used to be many rev

  • If the code is documented and someone makes a change to how a function works or is called, now they have to go back and change the documentation in all the places the function is used, they may even have to redo examples. This will likely take more time than the actual code change. Worse is if you actual decided to update the documentation you will discover that the last 5 guys that changed the code didn't update the docs correctly. You now have a massive mess that will take weeks to sort out, likely invo

    • Re: (Score:2)

      by Megane ( 129182 )
      If you change how a function is called, that's an API change, which rightfully should cause a documentation change. The documentation is there to tell you how to use it, and you've just changed how to use it.

  • ... say it ain't so!

    Slightly less funny -- why do you expect documentation to keep up with feature-creep? 'cuz people like writing documentation so much?!?

    Time was, learning to use your debugger and work around its' bugs was a rite of passage.

    • Time was the systems were simple enough that reading the code was feasible. Today you have not only lots of code, but lots of use of someone else's code that you also have to understand with the code as documentation model.

      Those times are over.

  • Seldom is the developer an expert in the domain their product is intended to service nor are they a part of the audience they intend to serve.

    Finding a common structure for documentation that works for more than just a handful audiences is challenging.

    There's a whole art of Knowledge Management that suggests that documentation is merely one of many instruments in the toolbox of knowledge transfer. The importance of documentation, it's format, and content are entirely dependent on what it's audience is expec

  • Go ahead, map the shores of the Mississippi river from it's source all the way to the Gulf to an accuracy of an inch. What do you mean it's banks shifted since you started and the map is no longer accurate... This is going to be true of any live and updated software. By the time you can completely document it with examples and reproducible test cases, the underling software will have changed, and the documentation will be out of date. It is only slow moving software that is completely documented, and to

    • Re: (Score:2)

      by PPH ( 736903 )

      By the time you can completely document it with examples and reproducible test cases, the underling software will have changed

      Whoever wrote the changes should also be writing the examples and test cases. And it should all be checked in to a repository as a package.

      the software needs a large number of users that are paying for it

      Who payed for the changes to the code?

  • Maybe because you don't hire tech writers? Back in the dark ages we employed people whose job it was to make good documentation.

    Yes, the programmer best understands the system, and that's the problem - what seems intuitive to him isn't going to necessarily be intuitive to someone just coming in and meeting the interface.

    Also, the programmer may understand how the system works, but not how it maps to the real world. I can tell you what the UI controls and the code does, but not necessarily what the user sh

    • Re: (Score:2)

      by PPH ( 736903 )

      Thank goodness our group hired a tech writer. Now I don't have to do documentation anymore and can get back to coding 100% of the time.

    • Once upon a time I programmed (embedded system) for a living.

      I gave my *engineering notes* to the alleged' Tech Writer.

      Supposed Tech. Writer took those *engineering notes* and made them, VERBATIM, the Product Manual.
      Look, I was the Programmer ("Software _Engineer_" is a title I was given but CANNOT -legally- claim) and *I* knew that was Just Plain Wrong. I pity the poor bastards that had to use that manual. Even more, I pity the poor bastards that had to use manuals said Tech. Writer "improved" - since...

  • I used to have header comments, copious function body comments, and I would happily whip up user documentation when the feature was complete.

    The problem I have now is that just because I consider good comments part of the coding process, very few other people do so the time allocated to my tasks don't include it. I write enough inline documentation for myself, but if you're someone new taking over my system, you have to parse through the code yourself.

    That probably isn't the end of the world—I work ha

    • Yeah, commenting is a lost art.

      I find that what I really want comments for is less "this is what the object or function is" and more "this is why this bit uses a non-standard or non-obvious way of interacting with something else". Particularly the ones that look like you really, totally, just oughta refactor that right away and it could be so much simpler... until you realize it was already simplified and covered the dear-god-WTF-would-anyone-do-that cases. Just state up front that that's what's going on, a

  • Git is reproducable ... huh? (Score:3)

    by bill_mcgonigle ( 4333 ) * on Sunday February 02, 2020 @10:51AM (#59681620) Homepage Journal

    > How would you make a worked example of a repository conversion that is both nontrivial and reproducible?

    Part of your documentation is a git repo that people can clone. From there you work them through editing the history with reposurgeon.

    Is reposurgeon nondeterministic?

    • Iâ(TM)m guessing he REALLY doesnâ(TM)t like to write docs, and this nonsense is just a convoluted attempt to trick some poor fool into doing it for him.

    • Re: (Score:3)

      by jrumney ( 197329 )

      reposurgeon is mostly about converting older revision control systems that don't do the job as well as git, into something modern like git, or mercurial.

      It needs documentation for all the ways you can get it to heuristically guess at the correct history when that information is missing from the source repository. Doing it manually is a massive amount of work for a large repository, and different historical workflows need different heuristics to get a more or less correct result.

      • I think you win the prize for the first person to comment here who has actually read the article. Or maybe just the summary.

        I know that "RTFA"-said-in-exasperation has been a meme here since the 1990s, but this is beyond pathetic. Of the ~70 comments scored 1 or higher, a couple dozen are people who know about "documentation", but don't know who ESR is, don't know what reposurgeon does, don't know what problem he is describing, and don't have any solutions. Another couple dozen do know who ESR is, and w

        • I know that "RTFA"-said-in-exasperation has been a meme here since the 1990s, but this is beyond pathetic.

          I guess lately a lot of people have given up on reading the featured article because lately, so many websites hosting the featured article A. block users of privacy tools, B. have put up paywalls, or C. both.

          • Re: (Score:2)

            by Megane ( 129182 )
            More like "C. submit them to sites like Slashdot / D. Profit!". Oh wait, were you doing multiple choice or sequential?

            • Re: (Score:2)

              by tepples ( 727027 )

              A. block users of privacy tools, B. have put up paywalls, or C. both.

              Oh wait, were you doing multiple choice or sequential?

              My comments have used "1. 2. 3." for sequential, or "A. B. C." for multiple choice. My comments have also used "or" for multiple choice.

  • In my meager experience, lack of documentation is the main barrier to contributing to open source projects. The first thing lacking is any explanation of the overall design of the code base. Next, looking at any module, there is generally no documentation about what that module is supposed to accomplish, or how it does so.

    As for Don Knuth, while I love the guy, his documentation is way overly verbose. Documentation needs to exist, but also be succinct. At some point, tl;dr.

    • Documentation is like food: more than you need is better than not enough. You can always just not eat it all. But the only way to get by with not enough food is to do less.

  • There's a heckuva lot of kinds of code. There is no one single way to write code, nor will anyone just be totally great at it if they learn The One True Way To Write It. There's no magic method that will make it easier. You have to actually stop for a minute, consider what you're trying to accomplish, and fit the code to the application.

    Same for docs. There is no one kind of "intro doc". Some applications can't even *have* an "intro doc", because the purpose of the thing precludes one introductory example o

  • Is that they literally wrote up one of their dogmas that code is more important than documentation, as though there is a problem with developers writing too much documentation. My experience is developers don't want to write docs at all and that only encourages people to write up no documentation or bad documentation that consists mostly of "No Shit Sherlock" sections.
  • The solution is fairly simple. Create one or more example repos of the various types and include it with the application. Then perform a tutorial based on the data contained within that example repo (obviously include directions on setting up the repos, maybe just sticking with the big types like git or subversion). Then you can show an example of how to modify the repo based on something that end users can see and replicate exactly and understand the ramifications of how it works.

  • It's a mistake for developers to write their own documentation. For a small company or open source project, there may be no choice. But for commercial software, technical writers USED to have jobs for a reason. Developers are victims of the curse of knowledge. They don't usually have the skill sets required for education and good writing. But now, companies have laid off their tech writers. It's all part of a greater arrogance that has crept into the industry... the assumption is that the design is SO GOOD

  • The best documentation is ... (Score:4, Insightful)

    by pz ( 113803 ) on Sunday February 02, 2020 @04:21PM (#59682546) Journal

    ... the notes I write to my future self about how to fix the thing that will undoubtedly happen again. I've given up trying to remember everything in my head (that stopped working about two decades ago), and document the solutions I come up with, either in code, or in a README file, or as comments emitted as part of a Makefile process, that will help me remember how to do thing the next time around.

    And there's always a next time around. Leaving my future self hints about how my past self did stuff, or even better, explicit instructions ("now that you've done step A, move to doing step B") is one of the best uses of my time because it's guaranteed to be a net gain.

    • ... the notes I write to my future self about how to fix the thing that will undoubtedly happen again.

      Years ago I maintained a database and we had a dog eared book with notes on what to do to maintain it and other advice; including tidbits such as

      “One must always run x at noon. I do not know why but evil things happen if you don’t.”

  • If something is a nontrivial challenge to document properly, perhaps that indicates a need to review the underlying code to see if it can be rewritten in smaller chunks where each step can be properly documented.

Slashdot Top Deals

Utility is when you have one telephone, luxury is when you have two, opulence is when you have three -- and paradise is when you have none. -- Doug Larson

Close