9 ms·

My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than a

• remotedeveloper 7y ago
  I work with a very large, complicated piece of software which has quite a comprehensive API but it's basically CRUD on top of a database. There is zero documentation about what happens when you update an object - only OpenAPI. To find that out, you would have to dig in to the database triggers. Half of working with it is trial-and-error and the other half is hope-and-pray.
  • JoeAltmaier 7y ago
    Same here. Why is documentation standard so low? Tell me how that buffer management works (do I provide it? delete it? when? how?); how threading is supported (reentrant? send/receive at the same time/different threads? interprocess?); dependencies (necessary initialization? teardown? states in between?); efficiency (can I hold a lock around the call? does it block?). Instead, we often get nothing but a method name and argument types. Ridiculous.
    • afarrell 7y ago
      > Why is documentation standard so low? Even in companies where good documentation would raise revenue in a way that the sales team notices[1], someone still needs to write it and someone still needs to make the business case for writing it. Engineers could, but many don't. If you're passionate about good documentation, but don't think you can deliver, it would be foolish to unless someone else is doing the writing. I'm a bit of an extreme case, but Many engineers feel so incredibly uncomfortable with writing prose that they avoid it. Why? The standard of writing education for STEM-minded people is low. Why? Writing education in high school is focused on literary analysis essays rather than on learning to describe facts and systems with vibrant clarity. [1] https://getputpost.co/overhauling-api-docs-with-gocardless-90cc2e656750 https://getputpost.co/overhauling-api-docs-with-gocardless-9... --- Anecdote: At age 14, my school had poster which listed the professions one could use mathematics in. Someone pitched us on how much need there was for people who could program. Shop classes and science classes had assignments which were miniature versions of problems we could see in the real world. Nobody did this for literary analysis. I didn't know how to ask "why are we doing this?" other than as a snotty teenager saying "Hey english teacher! Justify why your life's work has meaning." In reality, I wanted to say "I'm having trouble getting oriented around this subject. I'm having trouble understanding what it means to make progress or make something good. Can you help me?" I searched for writing advice devoured works like Politics and the English Language and Strunk and White. But they just helped me get better at editing, not at putting thoughts onto a blank page. Anecdote: At age 17, I told my English Literature teacher that I wanted to write really good physics tutorials. She looked confused at me and said "Why? Thats so boring." At age 17, I didn't have the self-confidence to persist to find a different teacher who would be interested in that. Anecdote: At age 20, in an engineering university, I knew that I struggled with getting the first draft of an essay done. I went to the writing center at my school. But I never built a good workflow with them for how to get the first-draft-writing process. I didn't know how to learn to write without an anxiety so strong that I felt compelled to dig my nails into my skin. I didn't know how to ask professors or TAs for help. I accepted that writing was just staring at the paper until my eyes bled. I wasn't going to learn to write. I endured my required writing classes. hoped that once I graduated, I might be able to work in a way to Anecdote: At age 29, I had to quit a visa-sponsoring software engineering job and very quickly find a new one, because of my failures with writing first drafts interacted with a business process for immigration-law compliance. --- I've now found two coaches and plan to spend this Saturday working on a first draft of a blog post and trying some of their strategies. Wish me luck.
      • zomglings 7y ago
        Good luck and, for what it's worth, that was a very well-written comment.
        • afarrell 7y ago
          Writing comments doesn't feel like "writing" to me; It feels like talking. I've actually written some pretty long comments on reddit. Yesterday, I talked with one of my coaches and put some thought into why: 1) I don't have any memories of feeling anxiousness from commenting on reddit. This is unsurprising since it has never been assigned to me by a teacher/parent. If I ever feel like "Its unclear why I would respond to this or what I would say to this", I just choose not to comment. 2) I have memories of writing a comment and other people upvoting it or telling me that it was helpful. I don't have this for essays. I driven by making people happy, so that is a meaningful reward. 3) Because of those positive memories, as I am writing, I can imagine that a sentence I am about to write is going to be helpful. That imagining is a bit of positive re-enforcement that I can chase, inherent to the task. It is like when I was a kid and I would do math homework and I would solve a problem and see that I'd solved it. It is one of the tricks of TDD. So, my plan this Saturday is to seek out the things that could possibly be intrinsically rewarding about writing: A) Look for interesting phrases that I can craft to clearly explain something. B) When I start on a section, write a question that someone could ask on a reddit thread, which this section answers. C) When I write a section, imagine myself saying this as an explanation in response to that question and imagine someone else expressing gratitude for that explanation. D) To avoid procrastination, mentally rehearse the act of starting and getting into the task. Simulate the trigger-response-reward in my mind so I can build the neural pathway. The reward I imagine should not be tied to completion, but come from the "I've just gotten started" state.
      • robotbikes 7y ago
        I think free writing such as journaling can help one get better at writing first drafts. Its important to practice the skill of getting something written.
        • 7y ago
    • michannne 7y ago
      Because docs take time to write, and good docs require a passionate dev who cares to write them
      • dragonwriter 7y ago
        Good docs take a dedicated tech writer who cares to write them. A passionate dev may or may not be a decent tech writer.
      • the_af 7y ago
        ...plus they tend to get outdated and out of sync with the code pretty fast!
        • dragonwriter 7y ago
          Not if the first step of updating the code is updating the documentation to reflect the intended state after the code update, preferably with embedded doctests that form part of the definition of done for the code changes. Sure, if documentation is treated as an afterthought it tends to reflect that attitude.
          • the_af 7y ago
            > documentation is treated as an afterthought Bingo. Do note that people here on HN live in a bubble where, for example, writing tests (any tests, not even good tests) is a given. But out there in the world there's plenty of software coding, a lot of it in major companies, where developers think testing is some cute but useless thing they teach you in college and which can be safely skipped, and managers are completely oblivious about this. Same with writing useful documentation.
          • dllthomas 7y ago
            In my experience, once you've got a bit of documentation, finding everything relevant to an intended change can be non-trivial and error-prone even if it's done first. For documentation to remain relevant there needs to be some kind of process actually checking every part of it against reality.
    • TuringNYC 7y ago
      >> Same here. Why is documentation standard so low? Because those who control resources make a conscious decision to prioritize new features and/or bug fixes rather than documenting what exists already.
      • xtiansimon 7y ago
        I really like writing the first draft of documentation. I get to run through the endpoints and even fine tune some of the details to fit to the big idea I'm creating about what the software does and how to use it best. The problem comes months later when I'm in the weeds and a colleague asks a question. I try to fob them off to the documentation, but some details are out of date. I pray it's just one detail, and that I don't have to stop what I'm doing to rewrite the documentation now.
      • chucksmash 7y ago
        That's part of it. Plenty of working developers will also omit tests and documentation even without the feature-factory time pressure though. A lot of times, the need for technical documentation isn't even a blip on the TODO radar. If I had a dime for every README where the last change was "Initial commit" and the file only contained # <PROJECT NAME> Service This is the new service for <TASK>. ....I could buy a good README.
    • dredmorbius 7y ago
      Another (possible) factor driving this is service- and support-based business models. Good documentation, enabling user self-support, eats both cost and revenue. (To what extent this is a conscious strategey and not simply decades-of-experience-born cynicism, I'm not entirely sure.)
• Consultant32452 7y ago
  I use javadocs all the time. Those are generated off comments in code. Is that the kind of thing you mean?
  • protomikron 7y ago
    Yes. Now if you use human language to document your functions (methods) that is not a problem, but too often I see something like: public class BookStore { ... /** * @param book The book. * @return The price. */ public static float getPrice(Book book) { return book.price() } } No shit sherlock! I admit that this is a contrived example, but you get my point.
    • acidburnNSA 7y ago
      Yeah, I was coming to say it can be done right, and that's your point too. If you spend the time to put what a thing does, why it does it, and how it does it, with meaningful hyperlinks to related things, then the auto-collected docs can be really slick. Maybe "auto-collected" is a better term for this than "auto-generated". I agree that auto-generated docs almost by definition don't add much. But if you go in and write narrative and have it get nicely collected into a slick hyperlinked webpage by things like doxygen and Sphinx, then that's great.
      • harimau777 7y ago
        It seems to me that the issue with auto-collected code is that, if done well, it captures the behavior of the code itself. However, it doesn't capture the specification of how the system should work (as opposed to just how it does work) or the higher level design and strategy of the system.
        • acidburnNSA 7y ago
          I agree with that too. There needs to be a lot of pure narrative in addition to the auto-collected API Docs. My big project has User Guide (with intro, vision, tutorials and how-tos), Developer guide (with architecture description, requirements specs, implementation overview) and then auto-collected API docs with all the details of how it's currently implemented. In the "notes" admonitions throughout the API docs, there's a some historical information and description of why it is the way it is and how it should ideally be (as appropriate). This feel like it works pretty well. Then again, I wrote a lot of it so I'm biased. There should be a roadmap somewhere as well, possibly in a Wiki or the developer docs.
• workthrowaway12 7y ago
  might be a swagger/openapi issue. golang for example does generated doc quite well imo. i wish other languages had the same.
• Waterluvian 7y ago
  When I was super green I argued about this with the principal engineer for quite a while about swagger. Docs generated from code do not define the contract, they describe the code-defined contract, bugs, accidental mutations, and all. How is that not a fatal flaw?
  • dtech 7y ago
    A separate specification works much better as long as that specification is also enforced during the build. A separate openapi spec that is not enforced can quickly become outdated, then an auto-generated from code is better.
    • undreren 7y ago
      You can add two new columns to your Kanban board called "Documentation" and "Documentation Review". Then tasks cannot move to your "Done" column unless documentation is written and passes review. If you enforce column limits documentation it will also block other tasks if not completed.
      • Waterluvian 7y ago
        In addition to this (and going a bit off topic). I've been adding checklists to Github PR templates (it's really easy[1]) for things like, "Did you re-read the relevant API docs? Do they need to be changed?" and it helps me a ton. [1] https://help.github.com/en/articles/creating-a-pull-request-template-for-your-repository https://help.github.com/en/articles/creating-a-pull-request-...
        • undreren 7y ago
          Checklists work so well. A kanban board has all the same qualities if used correctly :)
      • dtech 7y ago
        I have about as much confidence that is gonna work as I'd have in a (non-automated) "Test" and "Test review" column
• dtech 7y ago
  I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. This does of course require human-readable description in all the endpoints. But that's the same as only an autogenerated function signature in code documentation vs an added human-readable description.
  • protomikron 7y ago
    > I do not share your experience, because in my experience the auto-generated docs will be kept in sync with the code/API while a separate specification will become outdated over time. Does it? You can just alter the code and forget to alter the documentation above the functions/methods, so I don't think there is much of a difference. And wrong documentation is worse then no documentation. You have to write your documentation, keep it up to date and take it seriously. I would argue, if you have auto-documentation you are more likely to miss that, because you have some kind of documentation somehow - irregardless if it's actually useful.
    • 725686 7y ago
      "Does it? You can just alter the code and forget to alter the documentation above the functions/methods" Yes you can forget, but the barrier is much, much, much lower than having to modify a document god knows where.
    • ses1984 7y ago
      I've used swagger with java and golang and both of them generate docs directly from the code, no comments needed.
      • protomikron 7y ago
        But what's the point then? If there's a tool, that can make "documentation" out of source code, I can just look at the source code?
        • 7y ago
• xtiansimon 7y ago
  I've been trying to get my head around a particular Swagger project. Here is a funny email exchange from my request for documentation: ... Hi, I reaching out to to ask if I could get my hands on some documentation because the API is somewhat a black box to me. ... The api documentation for [product] can be found here: https://api.[product].com/ https://api.[product].com/ ... Sorry. That's not what I mean by "documentation". It's certainly non-linear. I don't know how to "read" this site to gain an understanding. It's kinda sparse: GET /v2/adjustments > Implementation Notes: Fetches a list of adjustments. GET /v2/reportCategories > Implementation Notes: Fetches a list of report categories. ... Hm, I think swagger documentation is pretty standard among APIs I've worked with before. I'm pretty sure it's all they have. ... "Swagger Documentation" is a special class of documentation for sure; Nobody likes writing documentation. Talk about insider (them)/outsider (me).
  • SamuelAdams 7y ago
    Isn't that the point of an API though? To be a black box? The example you provide is fairly simple: you hit these endpoints and get this kind of data. If you need to add data to one endpoint and see how that travels to other endpoints, that makes sense as to why you want documentation. In that case, a product / API tutorial or recipe (like the author suggests) might be useful.
• mfer 7y ago
  If you want your project to get real uptake and usage it's important to have fantastic documentation. Autogenerated documentation does no provide this. It is good as supplemental rather than primary documentation.
• random3 7y ago
  My pet-peeve is technical documentation that is not versioned with the code. I think you're confusing garbage-in / garbage-out or interface rendering with auto-"generated" documentation. Just like you can write bad code, you can write bad docs, not update them etc. The point of code generated documentation is not to render the interfaces but rather to keep code and docs in sync in the same place. It's more likely you'll se an out of sync / undocumented piece during a code review, in context, etc. then to assume it was updated somewhere else.
• rkangel 7y ago
  Documentation pulled out of code is only as good as the doc comments that have been written. It does have the advantage of making it far easier to write and maintain. If you're editing a function, if the documentation is just above then you're more likely to update it. This from the Rust standard library is a good example - https://doc.rust-lang.org/std/result/index.html https://doc.rust-lang.org/std/result/index.html . I think that's great documentation, and it's entirely generated from the source code. Most rust libraries won't have this level of explanatory detail, the core team have put a lot of effort into making it as easy as possible to learn, and documentation effort is part of that (the Rust book is another important part). Something else that Rust does well is that 'examples' is a standard part of project layout. For libraries that haven't done their top level documentation well, the examples folder will usually give a good demonstration of how to use the code, and they usually exist because that's the easiest thing for the library author, and the usually compile because they're automatically built by `cargo build`.
• blattimwind 7y ago
  > My pet peeve is auto-generated documentation from configuration files or source code. It is absolutely useless and I would rather prefer no documentation than auto-generated. For most applications this approach is generally useless and should not be used. Comments should be in the code itself, and you expect people who want to work on the application to read at least some of the code. I.e. no reference / API documentation for applications, instead high level overview (where is what, application architecture etc.) and guides (how to set up your dev environment, how to contribute, how to prepare releases etc.). For libraries it often makes sense to generate a reference documentation from the code itself. The drawback is that the strictly formulaic nature of comments parsed by the documentation generator has to be always kept in mind when writing the code itself. I.e. the comments need to make sense and be comprehensive when you remove them from the code surrounding them. Some modules in the Python standard library are a good example of this. Quite a large amount of prose, separate from the code, and then a reference section generated from code. However, many modules have pretty bad documentation, where even the reference is missing crucial information (quite often very basic things like what a function returns).
  • artursapek 7y ago
    > Comments should be in the code itself Rust handles this nicely; its generated docs are based off source code comments. Same with Golang.
• jerf 7y ago
  I have some Swagger-based documentation for a few APIs I've written, and I find it very frustrating because you can see in the renderers for Swagger that nobody actually documents with it. Nominally, several of the fields are specified as Markdown, allowing for useful formatting in your documentation, but what fields are actually rendered as Markdown in a given renderer is semi-random. The top-level description usually is, but a lot of the other fields come out random. In the worst cases, not only is the "Markdown" content rendered as plain text, it also is simply slapped between <p></p>, so the newlines are eliminated.
• franciscop 7y ago
  I have experimented with some tools to generate 3rd party docs for quick reference (didn't get far though). Not for my projects, but to analyze 3rd party project APIs. Why do you think it's useless? What part is useless? I am considering taking on this project at some point in the future. Edit: also I am referring to a library's API while I think you refer to a RESTful API. Would your comment also apply to libraries's API?
• weaksauce 7y ago
  I feel similar though it’s better than nothing to me. It’s feels like describing what a forest looks and operates by listing every tree in the forest. I want the higher level overview of component parts.
• simonsarris 7y ago
  We have a similar four-part documentation strategy: Tutorial, Technical introduction pages, Auto-generated API, and Samples Many people hate auto-generated API documentation because library authors do not write enough of it. For example here are my project's auto-generated documentation from source code, for two classes: https://gojs.net/latest/api/symbols/Diagram.html https://gojs.net/latest/api/symbols/Diagram.html https://gojs.net/latest/api/symbols/GraphObject.html https://gojs.net/latest/api/symbols/GraphObject.html That's 1238 words and 1408 words before you even get to the constructor. There should be a lot of information that comes out of the auto-generated API: What it is, what to know, different kinds of classes interact, and where to go next. Then of course a primary tutorial: https://gojs.net/latest/learn/index.html https://gojs.net/latest/learn/index.html And then conceptual Intro pages: https://gojs.net/latest/intro/index.html https://gojs.net/latest/intro/index.html (62 of them, covering everything from high level concepts to printing) Then, since so many people learn by example, hundreds of samples, organized with pictures and tags for each, with an explanation and commented code: https://gojs.net/latest/samples/index.html https://gojs.net/latest/samples/index.html
• GordonS 7y ago
  I find auto-generated documentation useful for libraries, and for powering intellisence kind of docs for libraries - it's pretty useless for anything other than libraries/APIs. Unfortunately, in my experience a lot of devs turn on auto docs in their project's settings and call it a day, especially if it's not a library/API!