1. 7

The goal is to have a prototype by the end of the week

I can see several problems related to that, when I get to work in big projects that exists for a long time, I usually spend a lot of energy to understand what is happening, what are the main elements, the domain entities. It might be because documentation gets unsynced with the code, but could be something else and what I’m going to do is to address this problem and produce a prototype by the end of the week. So if you have time, interest and energy, please contribute with insights. Thank you.

https://github.com/JpOnline/Blog/blob/master/documentation_sprint.md

  1.  

  2. 7
    • The most precise and concise and up to date documentation of a program is the code itself. If you aren’t adding value substantially better than improving the code itself, stop now.

    • Modern systems are so large, understanding them end to end is not humanly feasible, so don’t even try. Solution: The main criteria for judging a program design is how little you need to read and understand before you can make a beneficial change. Nothing else comes close. If adding documentation means you have more to read…. don’t. Rather change your design so you have less to read.

    • Documentation is all about audience and use cases. Be very clear about who you are writing it for, and what they will be using it for. If your audience is a programmer with good code navigation tools…. be very clear about what value you are adding.

    If you are not high on the Rusty Russel API design manifesto, for pity sake stop writing documentation and start cleaning up your apis.

    http://sweng.the-davies.net/Home/rustys-api-design-manifesto

    • Examples are useful. Unit Tests are examples that are proven to work and be up to date. They are your executable documentation. Make sure they are readable documentation. No ramble on tests, Use Given When Then and test one behaviour per test case.

    Here’s advice from the 1960’s. It’s still Good.

    Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious. Fred Brooks

    You asked…

    Would be a good strategy to write code documentation near the code it’s related to so it would be versioned by git?

    Definitely, use markdown (see what the linux kernel guys are doing). Being able to see the diffs is good. Wasting time on fiddling formatting is Bad.

    I hate fluffy cloud diagrams. They may mean something to you now, but they don’t accurately transfer knowledge between people.

    Architectural Decision Records are A Good Idea -> https://adr.github.io/

    1. 7

      The most precise and concise and up to date documentation of a program is the code itself.

      Up to a point. The code itself is the most precise and up to date documentation of what a program actually does. It is far from the most concise description of this, though: it’s actually the most pedantic and prolix (you could maybe argue that the compiled form is more precise and more pedantic, but I’m ignoring it here). Ultimately though, you need something else to tell you:

      • what the programmer thinks the software is doing
      • what anybody else thinks the software is doing
      • how the programmer expects you to use the software
      • whether the software solves the intended problem
      • whether the software solves your problem
      • why the software works the way it does
      • why the software was written the way it was
      • why the software wasn’t written in other ways it could have been (you pick up on this by mentioning ADRs)

      And this is one of two reasons why automatically-generated diagrams are only sometimes useful. By definition they show a subset of the information presented in the code, which is itself useful when the code is overwhelmingly pedantic (code editors have code folding for the same reason). But they don’t judiciously leave out information, in the same way that a knowledgeable person trying to construct a diagram in conversation with someone who’s learning about the system would: which is the other reason they are sometimes not useful.

      If adding documentation means you have more to read…. don’t. Rather change your design so you have less to read.

      I find the common failure mode for this “my code is self-documenting” approach is that the code author has typically spent a lot longer grappling with the problem and understanding its features than many readers would have, so has a unique impression of what can be expressed without documentation.

      1. 3

        what the programmer thinks the software is doing It doesn’t matter what he thinks it is doing, only what it does.

        how the programmer expects you to use the software Fact. Users don’t read documentation. They hate you and your program and the horse it rode in on if they have to read documentation to use it. Sad, not what I grew up on, but a fact of current existence.

        “my code is self-documenting” What I’m saying is not about self-documenting, it’s about designing code so your need neither to read documentation nor reams of code.

        The harsh vicious fact of life most code bases (if you include dependencies) are growing so fast, that even if you read all day everyday every second non stop…

        THEY STILL GET AWAY FROM YOU!

        You fundamentally cannot understand it end to end.

        That route is dead, no longer open to us.

        The only route left to us is to design things so we only need to read a small amount before we can make a beneficial change.

        1. 2

          (if you include dependencies)

          …which you only do if you think that “the code is the documentation”, because you can’t trust silly things like API docs. The point of packages, modules, APIs, whatever you want to call them, is that they allow you to avoid needing to transitively read and understand the code of all of your dependencies by just having to understand the interface.

          1. 1

            I’m currently forced to code to a black box proprietary interface for a certain device stack.

            99% of what I’m relying on is that it is reasonably well designed (by the Rusty Russel API Design manifesto).

            1% of what I rely on is the design / architectural conventions documentation.

            Alas, it’s ambiguous.

            I could answer my questions with 100% certainty if I had 20 minutes with the source code.

            I don’t.

            My productivity is throttled.

            1. 2

              You seem to be making the point that you need source code in case the documentation is bad - in which case, yes, you need the source code - but that’s not my point.

              My point is that with all current languages, good documentation beats out looking at the source code every single time - and it does, because no existing/widely used programming language is sufficiently expressive to show all of the things you put into documentation, such as design intent, and additionally, the documentation can be far more concise than the code by eliminating implementation details.

              1. 1

                No, my point is Good API design beats Documentation of all and any flavours every time.

                Unless your API design is excellent, wasting a single brain cycle on documentation takes you away from the more important task…. Improving your API.

                Sure, if your API design is excellent and you’re twiddling your thumbs wondering what to do next… Work on your documentation.

                I’m deadly absolute serious about http://sweng.the-davies.net/Home/rustys-api-design-manifesto

                Everything in my experience has hammered home the lessons in that manifesto time after time after time for 40 years now.

                Out of a rank of 1 to 10, where 10 is most important, “Read the documentation and you’ll get it right” is at a low number 3.

                1. 1

                  Good API design beats Documentation of all and any flavours every time

                  The only way this is possible is if you’re working in a programming language that is more expressive than English. Please show me what this language is.

                  1. 1

                    There are two flavours of documentation. User docs and dev docs.

                    Users don’t read docs unless they are desperate, and then hate you for making them do so.

                    I don’t write programs in English. I write them in a programming language.

                    If you have chosen your language well, it is the most concise, precise and expressive way of expressing the concepts involved.

                    English is neither precise nor concise. It’s expressiveness comes partly from overloading words and terms with meanings and values, and piling on adjectives at dire cost to precision and concision.

                    The joy and pain of computing (and mathematics) is it really doesn’t matter what you mean, only what your code does.

                    1. 1

                      There are two flavours of documentation. User docs and dev docs.

                      Yes, and English is superior to APIs/reading the code for both of them.

                      Users don’t read docs unless they are desperate, and then hate you for making them do so.

                      Doesn’t matter. Docs will still be superior to making them read an API or the code.

                      I don’t write programs in English. I write them in a programming language.

                      Doesn’t matter. There’s no connection between what language you write in and what language you document in. English is more expressive, and in specifically in important ways that make it better for documentation than APIs/code. Show me how to express the reason behind a design decision (e.g. you have to do x because of y, or because of historical event z), as opposed to implementing the design itself, in C, or whatever other language you use. You aren’t allowed to use comments, because those are English documentation, or convoluted code that is significantly different than what you would usually write.

                      English is neither precise nor concise. It’s expressiveness comes partly from overloading words and terms with meanings and values, and piling on adjectives at dire cost to precision and concision.

                      It can be very precise and very concise, and more importantly, it has the ability to express an entire class of necessary kinds of documentation, such as reasoning behind design decisions, that modern languages cannot.

                      Let me be more clear: modern programming languages do not allow you to express historical context or design rationale, both of which are very important for understanding nontrivial systems, and so lacking them is unacceptable - hence, English documentation is necessary.

                      The joy and pain of computing (and mathematics) is it really doesn’t matter what you mean, only what your code does.

                      This is only true in the most literal sense of that the computer doesn’t care what you mean. You know who cares about what you mean? Humans, which are who read and write code, and for whom code is executed. “Programs must be written for people to read, and only incidentally for machines to execute.” Therefore, API-only documentation is (1) objectively inferior and (2) unacceptable for development.

                      1. 1

                        Let me be more clear: modern programming languages do not allow you to express historical context or design rationale,

                        I honestly don’t care about such. That’s what commit logs are for.

                        If I was writing a history book, or trying to justify myself at a trial… Maybe.

                        All I care about are the constraints now, the behaviour now.

                        I don’t even care about intent, only behaviour.

                        I hate code that has the domain stamped all over every variable name and class…. and after wading through the whole thing up and down… I find it is something trivial and generic like a stack.

                        For pete’s sake, call a stack a stack. An preferably use a language that comes with one out of the box.

                        I want the humans, who are programmers, when they read my code, to read it using the rich and specialised vocabulary that comes with programming language and standard libraries I’m using.

                        Code is like group theory. It may be applicable in some domain. But if it is self consistent, and complete (in the mathematical sense)… it has uses that the author cannot imagine or intend.

                        1. 2

                          I honestly don’t care about such. That’s what commit logs are for.

                          That puts you in the tiny majority. The vast majority of programmers, including me, and probably every other one you know, want to know design rationale - because knowing that stuff is actually important, because design rationale encodes information that cannot be encoded in source code with any modern language - as a trivial example, the fact that a data structure is an array of records instead of a record of arrays for caching reasons. You cannot put this knowledge in source code - and as someone who eschews English documentation, you’re either going to be re-making a lot of mistakes, and missing out on a lot of performance gains, and opening security holes, because you’re limited to only the information in source code, or you’re working under conditions that aren’t applicable to, well, the vast majority of programmers - which is the target audience of the original poster: people who want documentation. Not you.

                          1. 1

                            Design rationale encodes information that cannot be encoded in source code with any modern language - as a trivial example, the fact that a data structure is an array of records instead of a record of arrays for caching reasons.

                            That may be the rationale you believe, I’d rather one of the tests include a benchmark that proves it. Beliefs about speed and caching are one of the areas programmers get wrong surprisingly often.

                            But you’re still missing the point.

                            The point is simple, it’s not “don’t document.”

                            It’s documentation is down at number 3 out of 10 in the list of priorities.

                            If you’ve hit priorities 10 to 4 as best you can…. go for your life. Document in away in Hebrew or Dutch or German and Greek

                            It’s A Good Thing. It makes life better.

                            Just take care to keep it up to date.

                            It’s amazingly easy to slip to level “-3. Read the documentation and you’ll get it wrong.”

                            In fact my experience is every project I have seen has some documentation at level -3.

      2. 1

        Definitely, use markdown (see what the linux kernel guys are doing). Being able to see the diffs is good. Wasting time on fiddling formatting is Bad.

        I hate the new Linux kernel documentation. The old plain text stuff is so much easier to consume than the new HTML-based documentation, it’s just insane how awful the UI of their documentation viewing website is compared to just opening CodingStyle in vim. As a programmer, I’m already very comfortable opening, reading, editing and navigating plain text files. It seems absurd to put documentation in any other format, to me.

        1. 1

          I understand your feeling, I really prefer vim to more fancy and visual IDEs, I think any developer prefer to write text to using some kind of visually alternative (like Scatch), but it might be good to identify what a rich visualization as html has to offer, like text different sizes, alignments, colors, images, interactivity, etc.

      3. 4

        I want multiple levels of documentation for functions and data structures - at the very least (1) a one-line summary so I can scroll through a page with one item per line (with little spacing) (2) a single paragraph and (3) the full docs.

        I also want something fast. There’s absolutely no reason for me to have to wait any perceptible amount of time (>200 ms) to go from one documentation page to another - the docs for almost every single project on existence (minus those with huge amounts of media) can fit into 1 GB of RAM, and modern computers are so fast that it’s trivial to pre-render all of the pages linked to the one currently being viewed.

        1. 1

          Nice requirements, thanks.

        2. 3
          • Documentation is more than comments or javadoc.
          • Documentation is more than just text.

          I view documentation as having four types:

          1. Tutorials: “How do I get started using this thing?”
          2. How-to-guides: specific technical docs on targeted goal-oriented topics
          3. Explanations and large-scale descriptions: focus on describing and understanding. Architectural descriptions, glossary, etc.
          4. Technical reference: in-detail descriptions on what happens. Generated docs. In-depth descriptions (possibly just pdfs of articles) of algorithms.

          Describing large architectural structures which are difficult to change tend to be more relevant for longer. The best documentation I’ve used describes projects at high conceptual levels, such as an block diagram at a very high level: “A sends messages of type M to B, which coordinates these changes with services C and D through our internal T protocol.” Glossaries of terms and abbreviations also help significantly. Describing “how” in code doesn’t seem to last, documenting “why” and the relationships between things tends to last longer.

          For technical reference, auto-generated docs: javadoc, sphinx, rustdoc, and doxygen seem to be the way to go. The focus seems to be too much on these though and there are other ways you can get information out of code: cinclude2dot and cflow come to mind. For diagrams, there’s Dia for manually created diagrams, graphviz for auto generating diagrams, and mscgen. Object-oriented Re-engineering Patterns recommends the use of dot-plots for code, but I’ve never seen it used in practice.

          1. 2

            I view documentation as having four types

            I like and agree with these categories. @smokeonline what I want is a tool that will separate out these things from each other, but link them together, so that when I’m in the learning stage I can read the examples and tutorials at the same time while dipping into the API reference occasionally, and then later after I understand the concepts I want to be able to exclusively read the API reference without those other things.

          2. 2

            One thing I think can be improved is removing the friction of writing proper commit messages when updating docs. I personally automate docs and other trivia commits with https://github.com/nikitavoloboev/gitupdate

            1. 1

              Whoever is following this post, I posted a follow up with the prototype https://lobste.rs/s/o42vrm/looset_promise_improve_documentation or you could go straight to it https://forms.gle/5vbfc54MRXcBodKc7

              1. 1

                I updated the github with a solution sketch and some maybe useful ideas. The main ideas are:

                • Using labels to define multiple level of documentation.
                • Run a basic static analysis to identify the function and where are they called to generate a diagram where you can filter elements you want to show/hide.
                • Run this analysis in any language.
                • Show usage examples of the code (tests) close to the code it tests.
                • Warn dev about missing code, maybe it was deleted or it changed the name.