[HN Gopher] The Surprising Power of Documentation
___________________________________________________________________
The Surprising Power of Documentation
Author : bndr
Score : 308 points
Date : 2023-06-12 02:30 UTC (20 hours ago)
(HTM) web link (vadimkravcenko.com)
(TXT) w3m dump (vadimkravcenko.com)
| regularfry wrote:
| "Documentation" as a term is almost catastrophically overloaded,
| and just "documenting" things is only half the battle. I'll take
| semi-documented systems if the information architecture is good;
| perfectly documented components in an unnavigable mess is no good
| if I can't find the document that would help me.
| arek_nawo wrote:
| I believe documentation can be highly beneficial, but only when
| it's done well. The article makes some good points on this, but,
| just based on experience and common sense, documentation should
| be centralized, clean and descriptive enough, while not being too
| wordy or plain gibberish.
|
| That's not easy to achieve and takes time and resources to get
| right. That's primarly why so many fail or give up on it.
|
| The results can very much be worth the effort, however, the ones
| who should be responsible for the documenting process likely
| don't see its importance. From their perspective, what they've
| worked on is easy to understand and requires little to no
| explanation. Taking time to change this mindset and create proper
| documentation is an effort many are unwilling to take.
| samsquire wrote:
| Documentation is where I go to find out the mental model behind
| the software.
|
| "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
|
| With the mental model of the software, I know where to go, where
| to look, how to change to fulfil my new requirements.
|
| I am thinking of writing a fictional documentation for a
| fictional operating system or library or web framework and then
| see where that design takes me.
| kartanaangel wrote:
| [flagged]
| euroderf wrote:
| Some nice quotes in this article that center on the idea of
| finding a better tradeoff between on the one hand, documentation
| as a vehicle for knowledge sharing, and on the other hand,
| meetings as a vehicle for knowledge sharing (when they should be
| about decision making).
|
| "You can think of Documentation as essentially the backbone of
| effective knowledge sharing."
|
| "In the words of Bukowski, 'Don't do it unless it comes out of
| your soul like a rocket', apply the same principle to meetings."
|
| "The constant need to have meetings is a symptom of a deeper
| problem -- a lack of clear, accessible, and reliable
| documentation."
|
| "Encourage your team to document their decision-making process to
| clarify assumptions, reasoning, and expected outcomes. Make it a
| standard practice to discuss these documented decisions in your
| meetings, promoting a culture of open feedback and collaborative
| decision-making."
| smeej wrote:
| All this assumes one important thing: That people will read what
| you put in front of them.
|
| I've been working in startups for several years now at companies
| of a variety of sizes, all of which were remote-first, and which
| (ostensibly) relied on writing to communicate.
|
| People do not read what you write. I don't know if they can't
| actually read fluently or if they won't, but it does not matter
| if I submit a bug ticket that says exactly what is happening and
| lists the ten things I've already tried to resolve it. 100% of
| the time, the first reply is to ask if I've tried doing any of
| the first three things I said I already tried.
|
| It's that kind of thing that makes me think documentation is
| hopeless. Nobody's going to read it anyway.
| lisasays wrote:
| _People do not read what you write._
|
| Then you need to move on, and find different people.
|
| Yes -- I know it's tough. The landscape out there is quite
| bleak, in fact.
|
| But these places, and these people do exist.
| [deleted]
| xyst wrote:
| I hate how true this is at most companies I have worked at.
| Invest a good amount of time writing up the docs and then a few
| hours later some asshole from another department has the nerve
| to ask me to "walk me through the process".
|
| Fuck you. I'll leave you unread until end of day then send you
| the docs you clearly didn't read.
| inconceivable wrote:
| whenever i run across this issue i literally just cut and paste
| (or screenshot selection) what i wrote before. you have to deal
| with the reality you are presented with, and unfortunately in
| this reality nobody reads a damn thing, or they skip every
| other line, or skip the middle n lines of a big chunk, or
| whatever.
| realjohng wrote:
| The only place where I've seen documentation done well was where
| it was enforced. For ex: if you're adding a new analytics
| tracking event, it must have corresponding documentation in
| internal wiki or build fails. It was annoying step but it
| enforced reliability of this wiki.
| briffid wrote:
| Most software documentation is: - the part of the software you
| didn't have the developer resources to implement - so you decide
| to write documentation to have the "code" that runs on the user's
| brain
| remoquete wrote:
| I think the most important message of this blog post is this:
|
| " Designating a dedicated team or individual for documentation in
| an early-stage startup can seem extravagant. But trust me, it's
| one of the smartest investments you can make. Why? Because
| knowledge is the lifeblood of your startup, and a dedicated
| handbook team acts as the circulatory system, ensuring that this
| vital knowledge flows freely and efficiently throughout the
| organization."
|
| So many startups lack technical writers, let alone docs teams.
| Not even OpenAI has one, as far as I know.
| ConcernedCoder wrote:
| omg if someone could just put some notes in their code... that
| would be a wonderful start...
| Lutger wrote:
| One of the surprising difficulties of creating a good culture
| around documentation I found is getting people to actually read
| and use it. I guess the root cause of this is bad documentation
| itself, so developers come to not expect to find anything useful
| in there and just ignore it by default.
|
| I've often seen developers who spend hours fiddling on some
| detail that was clearly mentioned in the readme of the very same
| repository containing the code on which they are stuck, or who
| just failed to read the extensive documentation and proceed to 1)
| run the code and 2) call me for help. Furthermore, I've actually
| caught myself doing the same more than once.
|
| This led me to think that for a good documentation culture, the
| primary question should be: how are developers actually going to
| use and benefit from the docs? How documentation will get updated
| is the second question of importance, and writing documentation
| comes third.
| macintux wrote:
| You're indirectly pointing to two ongoing problems with docs:
| discoverability and findability. Can you accidentally or
| purposefully find what you need to know?
| mewpmewp2 wrote:
| I admit, I rarely read documentation of anything, since I have
| no clue whether to trust it, so I will usually try to just
| follow my logical thought process of figuring out the solution
| or by trial and error.
|
| This also makes me bad myself at documentation, because if I
| don't use it I also feel internally that no one would read what
| I write in the first place also.
|
| Out of responsibility I will try to document shared things, but
| I never feel productive while doing that, I feel like I am just
| writing into a void.
| Cthulhu_ wrote:
| > I rarely read documentation of anything, since I have no
| clue whether to trust it
|
| There's another big issue with documentation; it's often a
| write-and-forget thing. I'm confident every team or
| department should have a full-time documentation owner whose
| job it is to ensure documentation is up to date, maintained,
| and verified.
| MetaWhirledPeas wrote:
| > I'm confident every team or department should have a
| full-time documentation owner whose job it is to ensure
| documentation is up to date, maintained, and verified.
|
| I'm not convinced this would work. Such a person wouldn't
| have time to be a subject matter expert at _anything_ other
| than the documentation tools. They wouldn 't understand
| what they were writing about.
| makeitdouble wrote:
| That happens when you have legal requirement on the
| documentation. The same way you have an accountant peering
| over and keeping track of every transaction that happens in
| your company.
|
| Short of that you'll need to explain why the company is
| losing money because Jim didn't write a full explanation on
| why his "getUserIdOrNull" function returns null when the
| user id is not available.
| zackees wrote:
| [dead]
| simonw wrote:
| I think one of the most important features for documentation is
| that it needs to earn people's trust.
|
| If people expect that the docs won't be comprehensive or will
| be out-of-date, they won't use them.
|
| This is why I'm so keen on documentation living in the same
| repo as the rest of the project. That way it can be kept up-to-
| date with the state of the code, through a policy where PRs are
| only merged when they include the relevant documentation
| updates.
|
| Having that policy in place really helps people learn to both
| write and read the documentation.
| mike_hearn wrote:
| I've done that and still do.
|
| It helps a bit, but only if your code reviewers are actually
| going to enforce the rule. It seems like most programmers
| simply don't like reading or writing documentation even
| though they can save large amounts of time for everyone by
| doing so. Certainly it's frustrating to be told e.g. "this
| thing we use can't do X" when how to do X is discussed in the
| thing's user guide, simply because someone didn't want to
| read it. I've had that experience before.
|
| Code reviews let you force the issue for a while but it's
| hard to scale. Getting other people to enforce the same rules
| via review is difficult. Many devs will be really strict
| about things like unit testing and make it a point of pride,
| but not at all strict at all about updating docs. Other devs
| will learn which reviewers let them avoid writing things in
| English and send reviews there preferentially, or find other
| ways to dodge it. Fixing this via training or policy turned
| out to be nigh-on impossible: many people simply _will not
| change_ regardless of how many times you send a code review
| back for missing docs. Nor will they change even when their
| questions are constantly being answered by a link to the
| docs, which they don 't take as "you should be embarrassed
| that I had to google that for you" but rather "hey here's a
| helpful link, you're welcome".
|
| Fundamentally there's a lack of shame about not reading
| things. It's not unique to software either. People ask
| questions answered by docs, or even by emails they just
| received, or they make bold assertions contradicted by docs
| they claim they've read, and when this is pointed out they
| just shrug it off in a way they wouldn't do if an obvious bug
| snuck through that should have been caught by testing. It's a
| cultural issue and needs to change, really.
|
| One fix I'm experimenting with at the moment is for a Linux
| kernel style hierarchy of reviewers where everyone gets their
| own repo and they merge upwards, so there's at least clear
| ownership and if someone is consistently letting docs rot
| that becomes apparent to the ultimate TL when they do a quick
| eyeball of big merges.
|
| It may also be worth experimenting with large language
| models. They could be given a change and asked, "given policy
| X, should this change have updated the documentation?" and if
| the LLM says yes then that gets flagged centrally for
| followup, for example.
| kwanbix wrote:
| In my experience, not everybody is good at writing good
| documentation.
|
| I usually see software build by brilliant engineers, people
| much smarter than I at building software, and the documentation
| sucks.
|
| Not that is not there, but that is very difficult to
| understand.
|
| It is clear to me that you can be very smart at doing certain
| things (for example writing software) and suck at others
| (writing documentation).
| BlargMcLarg wrote:
| Unfortunately, most cultures teach developers not to read.
| Between having barely any documentation, poor discoverability
| of said documentation, poor quality documentation, teaching
| people to 'talk at the first sign of trouble', it is only
| natural this is the outcome.
|
| Now we're stuck with both a chicken-and-egg problem at most
| places, while in places with decent documentation, many
| developers still come in not reading it, discouraging any
| significant upkeep of existing documentation.
| ponyous wrote:
| I never start with documentation, but I find it immensely
| useful. Usually it starts with someone asking about something
| and you can just link them to the docs without having to talk
| to them.
| yxre wrote:
| One thing said in another article that has really stuck with me
| on documentation is that it helps you scale yourself. You can
| only have so many meetings and so many discussions everyday.
| Maybe manage 5-10 people tops.
|
| With good documentation, it can be used to scale yourself beyond
| what you can personally do everyday, and it works really well
| when you can convince people to search for answers before asking
| revskill wrote:
| Suprise ? I thought documentation driven development is already
| the norm nowdays ? Is there other ways to do software development
| without documentation first ?
| c00lio wrote:
| Yes? Think of a few requirements, open an editor and try it out
| in code. Compile, put in front of users or colleagues, get
| suggestions, repeat. No docs necessary whatsoever. Half the
| world works like this.
| SoftTalker wrote:
| It's hard to argue with, especially if you've experienced using
| good documentation. OpenBSD's man pages are one example. It takes
| a little time to break the habit of checking Google first and
| instead checking the man page first (you eventually learn that
| you rarely need more than that).
|
| The key word is "good" documentation. That takes time and effort
| to write, and it takes time and effort to keep it updated as
| things change. As the author notes, it will have to be something
| that is made part of the culture of the organization. And given
| that recent agile programming approaches proclaim that "the code
| is the documentation" and that formal, separate documentation is
| an impediment to productivity, you'll find that many developers
| will dig in their heels if asked to write documentation.
|
| Bad, outdated, or just plain wrong documentation can be worse
| than nothing, as it tends to lead you to incorrect conclusions
| and beliefs about the system.
| eviks wrote:
| another key word is "searchable" documentation, and that's
| where man pages fail big time leading you to the likes of
| Google
| sarnowski wrote:
| What degree of ,,searchable" are you missing from apropos?
|
| https://man.openbsd.org/apropos.1
| eviks wrote:
| All of the basics of anything google-like: typo-
| friendliness with word forms and phrases, links to source,
| formatting of output, GUI, or not spamming the output with
| a dozen of lines of warnings that some man page files are
| missing.
|
| Then a bunch more degrees that I could know about if the
| tool were more usable
| BLanen wrote:
| Yes.
|
| I mostly use man pages when I already basically know the
| program and need to do specific thing.
|
| Even then I don't use man itself but usually a webpage of
| the manfile because of UX.
| euroderf wrote:
| Agreed on your last paragraph. One of my mantras to coders, as
| a tech documentarian, was that "Incorrect documentation is
| worse than no documentation".
| bruce511 wrote:
| All of the above. But as someone who writes documentation let
| me add, most programmers are bad writers.
|
| To write good documentation you need to mix technical reference
| (the easy part) with user reference. The latter requires you to
| imagine where the user is at, and take them to where they
| understand. This is hard to do, and requires well, skills.
|
| So a culture of documentation is great, but quality matters as
| much as quantity. Clarity, completeness and coherence are all
| legs of the stool.
| abraae wrote:
| Certainly writing is a skill that many programmers are not
| good at.
|
| However IMO an easy trap to fall into is to start documenting
| without a bigger understanding of the audience and the
| purpose of the doc.
|
| A good way to start is to identify which of the 4 types of
| documentation you are working on.
|
| https://nick.groenen.me/posts/the-4-types-of-technical-
| docum...
|
| Personally I find it very easy to put too much explanation in
| the wrong places.
| remoquete wrote:
| You also need technical writers.
| pacaro wrote:
| This issue around poor writing skills is something that I've
| thought/worried about for a while. At some level of seniority
| (the more junior the better IMO) we expect developers to
| write design docs. The inability to communicate clearly in
| those documents is a huge problem. Oftentimes
| misunderstandings and ambiguities are cleared up at design
| review, but then never reintegrated into the document,
| leaving two artifacts, the implementation and the design doc.
| These obviously drift over time, maintaining correspondence
| is hard. But when one only ambiguously described the other
| from the get go, then the documentation is broken. This too
| is technical debt.
|
| If you are fortunate, you can write code in an organization
| which has a high code quality bar, uses consistent styles
| etc. But it is rare (vanishingly so I nearly 30 years
| experience) to find the same bar applied to the design docs.
| makeitdouble wrote:
| > OpenBSD's man pages are one example.
|
| OpenBDS's developer to user ratio must be less that 1 to 1000s.
| When you update one line of document, you're probably saving
| time for thousands of users accross years of use.
|
| Most project I worked on had at most a few dozen people with an
| actual chance of reading the documentation, and the majority of
| them aren't users, they'll be reading all the code anyway
| because they're not in a position to blindly trust the
| documentaton.
|
| Why should we calculate the ROI of the time spend on
| maintaining good documentation the same way in both cases ?
|
| PS: I also think a distinction should be made between
| specification and documentation. It feels that both are
| conflated too many times.
| allknowingfrog wrote:
| ROI should always be a consideration. It's reasonable to
| argue the merits of documentation. It may even be reasonable
| to argue that most projects would benefit from increased
| documentation. Without knowing how long it will take to write
| it and how many people will use it, you cannot reasonably
| insist that writing more documentation should be a priority
| for every project.
|
| Much like automation, the question should be phrased in terms
| of how long it will take and how much time it will save.
| https://xkcd.com/1205/
| sodapopcan wrote:
| It was mentioned in a bullet point in the article a table of
| contents is really, really important if you want people to read
| your README. This is usually a no-brainer for libraries but I'm
| talking about company's repos for the applications they are
| developing. Often the READMEs are quite long and ain't no way
| anyone is going to scroll through an entire README in hopes that
| their question might be answered.
| gervwyk wrote:
| 100% this. And yes, good documentation takes a lot of investment
| but it pays off like compound interest. But with that done, it
| becomes even more important not to pull the carpet for no good
| reason, you are building a tower and documentation is at the
| foundation.
|
| We've built Lowdefy [1] as an open source project and documented
| it with all effort, 200 pages of docs. I often forget why or how
| something works and then jump to the docs. This investment keeps
| on paying of as we use Lowdefy to build customer apps, new devs
| in the team typically take less than two week to get up to speed
| and start making contributions, the sharp ones, just a two or
| three days.
|
| This year, we're extended our documentation onto customer apps
| aswell, with flow diagrams, state machine definitions, detailed
| field level explication schema definitions, and end user test
| procedures. The key here for this documentation is detail. It
| should be easier to reach for the docs and the the answer, than
| to dive in the code and interpret it.
|
| 1 - https://github.com/lowdefy/lowdefy
| gervwyk wrote:
| It is important to add to this a culture of actually reading
| the docs. Kudos here to my co-founder Sam. First developer I've
| ever met that reads ALL the docs before touching a line of
| code. When we say let's pick up some tech, he dives in and
| reads every page of doc he finds. The effect saves time and
| results in much much better technical decisions. You don't get
| stuck in the unknown, you immediately know where to go look if
| you are unsure, and architect a better big picture.
|
| This, given of course that the tech you are picking up has good
| docs.
| diarrhea wrote:
| I wish reading docs more or less fully was more normalised.
| Time and again I find myself suddenly the, or close to the
| subject matter expert just because I actually read the
| documentation of what everyone else had already been working
| with for years, but was new to me. I don't consider _knowing_
| a technology or tool without that step.
|
| As you said, without it, you're in the dark, doing guesswork.
| Doing that with multiple people, like a call with everyone
| guessing, is even worse. Just have everyone read the docs on
| their own time. So valuable.
| donkeybeer wrote:
| Whats the point in reading thousands of pages of
| documenation for an ephemeral and constantly changing
| project? In order to justify deep dives, the software
| itself has to be stable enough. I plan to read the entirety
| of the ANSI C specification for instance; it is a justified
| endeavour because ansi C is a stable standard with
| compilers implementing it for a long while. For a
| constantly changing project of course documenation is still
| important but it should be more geared toward quickly
| cluing you in on the specific part you are interested in,
| and hopefully make diffs easily presented and available.
| bambax wrote:
| We're currently trying to document an existing large Angular
| application and it's daunting. We wrote some meta-code to list
| all possible routes and attach components to routes (we were
| hoping Compodoc would help, but it doesn't work well anymore).
|
| We have over 700 routes (screens), 1200+ components and 500+
| different service calls that query APIs in the back end. If we
| only look at routes and hope to spend, on average, one day per
| screen, that's 700+ days of writing docs, which is a considerable
| amount of work.
|
| There's no existing documentation, save for 30,000+ JIRA tickets
| over a 5-year period, that describe various bug fixes and change
| requests. But those tickets are just floating in the ether and
| are not formally attached to any specific component, let alone
| route.
|
| I was hoping AI would help but I can't seem to find anything
| relevant.
|
| What would you do?
| Klaster_1 wrote:
| As a fellow Angular developer at a similar state of affairs, I
| am curious as to what problems you think documentation would
| solve, how you plan to maintain it after more "Jira tickets"
| layer up and what's your general strategy.
| bambax wrote:
| We hope it will save time when assessing bugs and describing
| new features, by providing a base reference of what the code
| currently does.
|
| We intend to have designers update the doc when describing a
| change request, and the devs also update the doc afterwards.
|
| We're not sure any of this is going to work; in the life of
| the project there has been at least two major documentation
| efforts, that failed because they were eventually abandoned
| (not maintained).
|
| Some are still hoping there's some kind of magic bullet that
| would let us automate everything... and I'm not immune to
| this myself.
| r_hoods_ghost wrote:
| Hire a couple of technical writers with experience and let them
| get on with it, and then make your devs document every new
| feature and change. Nothing passes code review unless it is
| accompanied by updated documentation. Getting your devs to
| document the existing codebase when you've inherited a shitshow
| like this will pull them away from their jobs for too long.
| onion2k wrote:
| _What would you do?_
|
| Accept that it's a big job and just get on with it. Sometimes
| we just have to do hard things. Putting it off or looking for a
| shortcut doesn't always work.
|
| I'd also spend a couple of months seeing how much of the
| documentation production I can automate though. That's a small
| investment in a 700 day project.
| bambax wrote:
| Yeah. There's this quote I love:
|
| > _If you have a mountain of shit to move, how much time
| should you spend looking for a bigger shovel? There 's no
| obviously correct answer - it must depend on the size of the
| mountain, the availability of large shovels, how quickly you
| have to move it etc. But the answer absolutely cannot be 100%
| of your time. At some point you have to shovel some shit._
|
| From https://www.scattered-thoughts.net/writing/things-
| unlearned/
| paddy_m wrote:
| The corollary is also important. If you are writing code
| you should want it to solve a problem, and for it to be the
| chosen solution regularly. Make sure people with the
| problem you are solving know that your solution solves
| their problem, and how it solves their problem. That's the
| point of documentation.
| inconceivable wrote:
| do you have usage analytics or ticket token analytics? i would
| document the most commonly accessed/used stuff first.
|
| and make sure this is at least one person's actual full-time
| job. chances are you'll have to hire specifically for this role
| because nobody wants to be bait-and-switched into this job, but
| there are actual professionals that do this for a living.
| magicalhippo wrote:
| We're in a similarish situation. We decided to accept spending
| a bit of time on the documentation every time some JIRA ticket
| requires us to work on an undocumented section of code.
|
| Not everything requires a lot of documentation, we have a lot
| of essentially glorified input dialogs, but we do try to write
| down what it is, and especially any logic and config settings
| that affect that logic.
|
| One thing I've used before with success and which we've also
| introduced was two new fields in JIRA, "requires documentation
| update" and "documentation updated", to aid not forgetting to
| update documentation when adding or changing code.
| bad_username wrote:
| I would go from the most pressing problem, apply the Pareto
| principle to solve it, and repeat until reasonably happy. What
| is the biggest actual pain that the current lack of docs
| causes? I do not yet know the answer (feel free to share), but
| there is a good chance that the problem does not actually
| require a formal description of every screen one by one. You
| may be trying to create reference docs where higher level and
| more abstract documentation is warranted.
| abraae wrote:
| > If we only look at routes and hope to spend, on average, one
| day per screen, that's 700+ days of writing docs, which is a
| considerable amount of work.
|
| It sounds like you're thinking about the really boring kind of
| documentation. The kind that no one wants to read and certainly
| no one wants to write.
|
| In some approaches, the 4 types of documentation are tutorials,
| how-to guides, technical reference and explanation.
|
| Any per-screen documentation is not tutorial, how-to or
| explanation. Perhaps it might be technical reference.
|
| The first question then is why are you working on technical
| reference? Would you get more bang for the buck writing how-to
| guides?
| bambax wrote:
| We have docs and videos and whatnot, that describe how to use
| the application in order to accomplish a given task, in
| general terms (find some entry in the menu, go there, click
| that button).
|
| What we do not have is something that describes exactly what
| the system is supposed to do, so that when one stumbles upon
| an unexpected behavior, they don't know if it's a bug or if
| it was intended that way (it could be either, depending on
| old requirements that weren't properly written down).
| auggierose wrote:
| > In the words of Bukowski, "Don't do it unless it comes out of
| your soul like a rocket,"
|
| Given that Bukowski said that about _writing_ , it applies more
| to writing documentation, than to holding meetings. So exactly
| the other way around than presented in this article.
| w10-1 wrote:
| Documentation is controversial because
|
| (a) it's an ambiguous material (like wood), so anecdata go all
| ways
|
| (b) it's for the future, i.e., easy to cut in a time pinch
|
| (c) it presumes knowledge is shared, though it's often hoarded
|
| (d) it's a tax on everyone's time
|
| A helpful discussion of documentation would focus on specific
| use-cases: on-boarding developers, backgrounding design
| discussions, operational run-books...
|
| In that context
|
| (a) The cost/benefit is concrete
|
| (b) You've identified the consumer/stakeholder, so they can speak
| the the present value
|
| (c) Present work is value in terms of that future product
|
| Then some documentation strategies become clear:
|
| (1) Write for some specific reader. It's not a brain dump (unless
| it is, e.g., for departing engineer).
|
| (2) Build in feedback cycles with actual users before completion
|
| (3) Make it someone's job (put them on the hook) to deliver good
| documentation (for all users). They can optimize extraction and
| repurposing across the organization.
|
| If I see director+ level people with no strategies for
| documentation, I conclude they're not building an organization.
| swayvil wrote:
| First and foremost, who are you talking to?
|
| Second, keep it plain and succinct. No convolution. No wordwalls.
|
| Third. Use pictures and diagrams whenever possible.
|
| (From my father, a technical writer of some renown.)
| entropyie wrote:
| I'm going to go out on a limb here and say that startups should
| be investing spare cycles in automation moreso than
| documentation. Do you want a 100 page install guide or a fully
| automated install script? Which one is more likely to be kept up
| to date? Which one is more likelybto have people notice it's out
| of date and fix it? Documentation is helpful, but automation is a
| force multiplier.
| Groxx wrote:
| When the automation breaks, and it always breaks: gimme that
| 100 page doc please
| Multicomp wrote:
| I write automation constantly as my full time job.
| Documentation of how to do processes manually is definitely
| ripe to be automated.
|
| But what parameters are available for the automation? Where
| does the automation live? How do you diagnose and improve when
| the automation breaks? Why did we even make this automation in
| the first place?
|
| These sorts of questions are ripe for documentation. Most How
| style questions can be automated in one form or another. But
| the business process behind the automation, the context and
| domain knowledge around the autmation, for the humans who did
| not personally code it, documentation has major benefits that I
| think we as an industry don't value enough.
| marcosdumay wrote:
| > But what parameters are available for the automation?
|
| A case of non-automatic automation :)
|
| Actually, there's nothing wrong with that. Many things are
| best left that way. It's just an interesting oxymoron. And
| it's also interesting the fact that yours (and I'm sure many
| other's) mind jumped directly into it.
|
| Automatic automations also exist. And those require a
| complete different set of documents.
|
| But anyway, they are important because the "how do they
| work", "how do we fix (or improve) it", and "what can they
| do" are trivial to deduce from a working artifact. Those are
| not questions you usually want to answer with text.
| dimal wrote:
| Having just experienced a startup that attempted to do what you
| suggest, I will say that in this case, it did not work. First
| of all, there is so much more institutional knowledge to
| document than just installing something. Second of all, the
| first step in automating something complex is to document what
| it is to document.
|
| If there is no documentation for the system architecture or how
| to solve common problems, everyone on the team wastes cycles
| solving problems that others already have, and doing it in
| different ways, so the codebase becomes an inconsistent pile.
|
| Documentation is truly a force multiplier. It allows an entire
| team to learn from the experience of a single person, and that
| person can help the others passively and asynchronously.
| 0x445442 wrote:
| It's not just startups. I've been working in "The Enterprise"
| for 28 years and with one or two exceptions, my time would have
| been better spent automating internal processes that were
| documented than working on the actual product. And by better
| spent I mean the money saved in person hours manually and many
| times errantly repeating tasks that could have been done by
| software, exceeded any revenue generated from the product
| software I was working on.
| Maxburn wrote:
| Excellent point. Even as a non developer we are automating
| things like deploying databases for a application and complete
| system backups. We pay for that app to be developed but it pays
| off 200x once it's deployed and realized across all the like
| systems we manage.
| Capricorn2481 wrote:
| > Do you want a 100 page install guide or a fully automated
| install script
|
| Is there an example that actually happens? A system requiring
| 100 pages of documentation just for installing is not getting
| done in a single script
| eschneider wrote:
| The real reason to write good (or at least minimally viable)
| documentation? The person who's going to need it most is Future
| You. When Future You has to return to a project a year after you
| last looked at things, you will than Past You for writing things
| down.
| nickdothutton wrote:
| I've worked at a few startups, 1 or 2 that grew large (from <50
| people when I arrived to tens of thousands of staff around the
| world). If your sails do catch the wind and you have to scale up,
| then documentation is invaluable (that and automation).
| Documentation needs an owner though, because it generally has a
| half-life and decays over time. This kind of ownership has to be
| enforced.
| cracrecry wrote:
| Mmmm, we believe papers are not enough to document code. We use a
| lot REPLs in Lisp and python for that.
|
| Most of the time, this means making things smaller and modularise
| those. It takes a lot of work and there is always an initial
| resistance from the team for doing it. But it doesn't take much
| for them to realise how powerful and useful those interfaces are
| once they are in place and work.
|
| A paper alone with code is kind of dumb, you need something
| people can interact with by discovery, by doing, experimenting,
| just like we do as children with the world surrounding us.
|
| Just having some explanation is not enough: People just don't
| understand things reading about them, but formulating hypothesis
| about their understanding and confronting those with reality.
|
| Without them, people are not going to be understanding what you
| believe they are understanding, but their own idea, that is often
| totally wrong.
| [deleted]
| dschuetz wrote:
| While I agree that docu is important I've seen my share of
| garbage poured into wikis and presented as the single source of
| truth. It takes a lot of time and effort to make docu meaningful
| and useful with the outlook that it's ignored and overlooked
| anyways. Quality documentation is expensive, and, if one invests
| heavily into it there must be a clear workflow path that makes
| following and reviewing docu mandatory. Documenting for the sole
| reason of existence of docu is counterproductive.
| hahnbee wrote:
| stale documentation is worse than no documentation
| Multicomp wrote:
| The cause of stale documentation? Not writing documentation.
|
| According to this saying, the fix to stale documentation is
| (often implied) to not write documentation. Can't go stale if
| it doesn't exist!
|
| The above saying is so often used as an excuse to write no
| documentation so much that while stale documentation can
| provide more acute pain than no documentation, the chronic
| pain of no documentation is a cure worse than the disease.
| hahnbee wrote:
| Ah I can totally see how my simple statement can imply that
| I would advocate for no documentation. This wasn't my
| intention. I think it's important to provide all team
| members with resources and guidance on how to maintain
| documentation so that it doesn't go stale. Documentation
| requires extra time and maintenance but providing tools to
| decrease the effort to ensure that written documentation
| doesn't go stale is important for every technical team
| leader to do.
| marginalia_nu wrote:
| Problem with documentation is that there are a lot of uses for
| documentation. It can be a reference, it can describe the
| architecture, it can do many things. Probably a good idea to
| figure out what the intent is first to find a good form.
|
| Some of my stuff is pretty sprawling, I've started integrating
| the documentation with the code and basically use readme.md's
| littered in the code as sign-posts to let you navigate it more
| quickly. The intent of that documentation is pretty clear, and
| the shape follows logically.
|
| e.g.
| https://github.com/MarginaliaSearch/MarginaliaSearch/tree/ma...
| regularfry wrote:
| Hesitant though I am to recommend an approach to structuring
| documentation which needs its own documentation, the structure
| followed by the Django docs is straightforward to apply:
| https://mattsegal.dev/how-to-read-django-docs.html
| LT_SPA wrote:
| > Do you know how sometimes there are articles that have a
| 2000-word introduction to that one sentence that you need to
| solve your problem? That's what over-documenting can feel like.
|
| Good reminder.
| 63 wrote:
| I'll add that what a lot of non-developers seem to think is
| documentation is not actually worth very much. For instance, a 2
| hour recording of a zoom meeting tagged only with a date and
| general topic is worth so much less than a searchable text guide
| on the same topic. Recording a meeting is not documentation!
| Especially if it's not tagged properly and made available to the
| people who need it. It's also impossible to update a meeting
| recording of course so it's guaranteed to be out of date after
| enough time passes, requiring that meeting to be held and
| recorded again.
|
| Other things that I see treated as documentation when they're
| not: slack messages, uncommented code ("self-documenting" code
| exists, but it's much rarer than management seems to insist),
| vague jira tickets, some guy who worked on the app 5 years ago
| and is happy to answer questions even though he's in a new role
| now, etc.
| elmolino89 wrote:
| I have found that the post meeting notes written by at least
| two persons then consolidated and improved by others really do
| help. Recordings while better than nothing would have to have
| transcripts in order to be usable. Hard to watch hour long
| recording searching for the relevant 5mins.
| mailund wrote:
| This is one thing that has always bothered me! A lot of clients
| ask if I have checked the documentation when I have a very
| specific question. The documentation however, is just a drive
| of a bunch of recorded meetings with no tags or transcripts. Am
| I really supposed to linearly look through tens of hours of
| recorded meetings to see of the detail might have been
| mentioned on one of those?
| c00lio wrote:
| If they are clients or people responsible for any kind of
| budget, just phrase it as a business offer: I can watch
| through the 89 hours of relevant documentation in 89 hours
| for $165 an hour. Pricing fixed if accepted within 2 weeks of
| offering date.
| SkipperCat wrote:
| I can't stress this enough. Know your audience and tailor your
| documentation to them.
|
| You should write three types of documentation. One for users, one
| for admins and one about architecture.
|
| User docs are simple. How do I use it. What are the API calls,
| etc. Admin docs are about how to install/break-fix/troubleshoot
| issues that are beyond user interaction. Architecture is how the
| system is constructed, why certain tech was chosen, etc.
|
| There's nothing that makes documentation more useless than when
| you're trying to do something like install the software but you
| have to dig thru piles of docs about why Postgres was chosen over
| MySQL. If your users or admins cant find the info they need
| quickly, they'll soon discard the documentation and user/system
| ops will go back to word of mouth knowledgeable.
|
| I really think good companies focus on this and those who are
| successful really shine.
| crispyambulance wrote:
| I agree with everything you said, especially tailoring
| documentation for intended purpose.
|
| Except... > User docs are simple.
|
| User docs are NOT simple. You have to put yourself into the
| mind of someone who is going to use your software to solve a
| problem which they have. That's never easy and it gets really
| hard, really fast, as the software grows in complexity or as
| your audience gets wider.
| muser8 wrote:
| To continue this line of thinking: for documents to be useful
| in helping a customer solve a problem the documents must
| answer the question 'why would I want to do X.'
|
| A complete reference of how to do A, ..., X, Y, and Z but
| lacking conceptual context could actually be detrimental to a
| customer's productivity and the ultimate success of your
| product.
|
| Providing accessible conceptual guidance can be very
| challenging depending on the domain.
| Cthulhu_ wrote:
| There's another category that's missing from most of the
| (enterprisey) companies I've worked at; procedures. Think of
| the result of an event storming session; consider all the steps
| involved in all layers of your application when a user creates
| a new session, or wants to do X in your application.
|
| Ex: I work in the energy sector at the moment; because their
| gas/electricity usage varies across the year, there's a system
| in place where they pay a fixed amount per month, then they pay
| or get paid back the difference by the end of a contract year.
|
| It's in the energy company's best interest that the monthly
| amount they pay is on par. The process to adjust this monthly
| amount is administrative, but in addition to that there's a
| huge stack of things to deal with across platforms; website,
| apps, back-end, support, support user interface, etc etc etc.
|
| All the processes involved in just this aspect of the company
| need to be documented and drawn out as well, because else it
| has to be figured out from code or various people that happen
| to have it in their head. That's where a lot of the meeting
| culture comes from, because there's no one person in charge of
| this process, and the ones that know enough don't get together
| to write it down (and then maintain that documentation).
| mwilliamson wrote:
| Reminds me of the four types of documentation that sometimes
| get listed: tutorials, how-to guides, technical reference and
| explanation. (Usual caveat of all models are wrong but some are
| useful.) https://documentation.divio.com/
|
| My (perhaps overly simplistic) take would be that we should
| take the thinking we use on the product itself (Who's going to
| use it? In what context? What would they already know? And so
| on), and apply and adapt it to the docs as we would any other
| product.
| dotandgtfo wrote:
| I strongly back the Divio system for documentation, it works
| great. But you should know that the creator of the system
| doesn't work at Divio anymore and the newest iteration is now
| called Diataxis https://diataxis.fr/
| ren_engineer wrote:
| the divio style docs concept got further refined by the
| creator with this - https://diataxis.fr/
|
| mostly the same but some additional information for people
| who are interested
| alexpotato wrote:
| > You should write three types of documentation. One for users,
| one for admins and one about architecture.
|
| I use an airplane analogy (different order than your three
| above):
|
| 1. "Congratulations on purchasing your 747"
|
| 2. "This is how you replace the auxiliary power unit"
|
| 3. "This is how you survive the engine catching fire"
| remram wrote:
| 1 is not documenting anything, and both 1 and 3 are meant for
| pilots? Who are the "users" in this analogy?
| JdeBP wrote:
| On the contrary, 1 would be a "quickstart guide", a
| "welcome pack", or even just a "The first thing that you
| need to do to your new washing machine/jet aircraft is take
| the restraining bolts, used for immobilizing it during
| transport, off."
| nwatson wrote:
| "1" is for the airline. What does purchasing the plane, or
| a fleet of such planes, mean to the company? What will be
| the benefits, duties, obligations wrt to the airplanes, at
| a high level?
|
| Edit: word choice
| [deleted]
| MilStdJunkie wrote:
| Surfing close to Robert Horn's Information Mapping. Which is a
| useful construct, but it's a dangerous idea to think that
| content information types just sort of live . . out there,
| somewhere. Content typing will always be context - dependent,
| which, well, can boil down to "know your audience". But the
| content types aren't General Truth, they _do_ need audience to
| be defined, which is where I disagree with the DITA folks.
| makeitdouble wrote:
| It could help to use more specific terminology than "docs".
|
| If I'm properly getting your point, you think there should be
| user manuals, administration and maintenance procedures, and
| architecture specifications and/or decision records.
| NiklasBegley wrote:
| Agreed on a lot of this, but I'd be cautious about saying that
| any kind of documentation is "simple". Especially when it comes
| to technical products - be they internal or external.
|
| Technical writers train specifically to communicate complex
| technical topics to readers, and it's not an easy job. It
| requires understanding your readers, what kind of backgrounds
| they have, and what are they trying to achieve. This becomes
| especially important for documentation that is meant for your
| customers, where very real revenue depends on the quality of
| your docs.
|
| I'm a bit biased since I'm the founder of a documentation
| startup [0], but tools also do play a big part. Devs often tend
| to enjoy writing something Markdown next to their code than
| going to an old wiki like Confluence that's disconnected from
| the engineering cycle. Choosing the right tool lowers the
| barrier to keeping the docs up to date.
|
| [0]: https://www.doctave.com
| jrumbut wrote:
| > disconnected from the engineering cycle
|
| Great phrase!
|
| To me, there are three places that dev-generated
| documentation can live:
|
| 1. The code
|
| 2. The issue tracker
|
| 3. The version control system
|
| A small amount of exceptionally useful and frequently
| referred to documentation like the process for setting up a
| new dev environment or some complex support task can live
| elsewhere.
|
| Otherwise, I think the top down imposition of a documentation
| culture is unlikely to succeed.
|
| The real secret to getting a team that has a shared
| understanding of the system, the business, and each other is
| to retain your developers. A team that's been together for
| five years has superpowers no amount of documentation can
| replicate.
| ChrisMarshallNY wrote:
| I'm big on documentation, but it needs to be done correctly.
|
| I have a bit of a screed on the topic, that I did, a while back:
| https://littlegreenviper.com/miscellany/leaving-a-legacy/
| antupis wrote:
| Personally I think at the age of LLM lots of up-to-date
| documentation will be those superpowers that will boost some
| companies to whole new level.
| hahnbee wrote:
| Agreed, Chatbots will make it a lot easier for the discovery
| process of documentation.
| makeitdouble wrote:
| Is it naive to assume that we could have bots actually read the
| code and come up with an "understanding" of what the code does
| instead of the metadata written by a human for humans on the
| side ?
| monkeydust wrote:
| Yup.
|
| Were using LLM retrieval methods to build Q&A bots at work.
| These are all fed with documents (user guides, release notes,
| transcribed videos etc).
|
| Its still very much POC but the interesting thing is people
| seems to care about documents again a bit more knowing that it
| will be used in this manner.
|
| I was thinking about developing something that rewards document
| producers if their response is cited and used successfully -
| would help strengthen the feedback loop.
| pixel3234 wrote:
| I have moderate successful Java library. Problem with
| documentation is:
|
| - it takes effort to write it
|
| - there is a split between what documentation describes and
| reality
|
| - it falls behind as new stuff develops, project gets forked,
| taken over...
|
| My solution is to have code examples, that are part of unit
| tests. Separate folder that describes most common use cases. If
| documentation is wrong, project does not even compile or test
| fails. And I can always point to most current version of examples
| in git branch.
|
| I really think any document beyond simple readme.md is overkill
| for most projects.
| rho4 wrote:
| In my experience, documentation becomes outdated and fragmented
| very fast. If I had a say, I would make a rule that every
| employee should maintain only up to 10 wiki single-pages for
| their most important products, components or processes. At the
| top I would require a system overview diagram. And no details,
| only high-level concepts, keywords, pointers, links and contacts.
| oneshtein wrote:
| Can you show us "definition of done" for your process of
| closing a ticket? It looks like the "* [ ] update relevant
| documentation and list link to the documentation changeset"
| step is missed.
| franciscop wrote:
| This is too biased for-docs IMHO*. I do agree with many points,
| documentation IS amazing, and you are very likely under-
| documenting things in your company. But documentation is not
| cheap to create, and specially it's not cheap to maintain. If you
| are not writing enough yes, sure, that's probably a great
| investment, but start bit by bit.
|
| I've worked in _multiple* companies where the problem was too
| much documentation, and of course everyone was afraid to update
| or_ ghasps* remove any piece of old documentation in case it was
| still useful. Imagine working on a codebase where 80% of the code
| was unused or commented out but no one dared changing it just in
| case (flashback to 2010 with 4000 lines of style.css).
|
| I'd suggest to take a more holistic approach and treat
| documentation a lot like testing; for that prototype, probably
| just write the barebones documentation, for the production-ready
| new feature go all-in and write detailed documentation,
| tutorials, etc.
|
| If you do want to go deeper with documentation, then you'll need
| a dedicated team (like a team of testers) that work exclusively
| on documentation. At some point it does make sense to hire only
| for that, and it can even be a differentiating point for your
| startup if done correctly.
|
| For libraries, a ratio I've seen works pretty well is approx
| 1:3:5 for lines of code:tests:docs; you can do tests first, or
| even documentation first, but once everything is finished and if
| you count the amount of lines that's a decent ratio. Note that
| when counting "lines of docs" in an editor, a whole paragraph
| will count as just 1, so in reality there's a lot more docs.
|
| Note: I'm the creator of both https://documentation.page/ and
| https://documentation.agency/
|
| * (only 2 "negative" paragraphs on a book-length article)
| johnnyanmac wrote:
| >I've worked in multiple* companies where the problem was too
| much documentation, and of course everyone was afraid to update
| or ghasps*
|
| That must be nice. I've yet to work on a company where half my
| time wasn't trying to prod for some resource (be it internal
| code, a public 3rd party tool, or even the resource itself),
| sometimes playing a game of goose just to figure out who knows
| the author. I'd love too much documentation.
|
| But I understand your point. The only thing worse than no
| documentation is _wrong_ documentation, and outdated docs half
| the time can become outright wrong half the time, if it isn 't
| simply encouraging outdated but functional practices. Tech
| writers are highly undervalued for that purpose.
|
| I should also mention that the ability to properly search for
| docs is almost more important than the doc itself. Some
| companies had wikis but good luck searching for the right
| keywords if you didn't know the exact title. A properly
| categorized top level page could have helped a lot (and is
| probably easier/cheaper than integrating google like
| searchabilty into an internal database).
| franciscop wrote:
| > That must be nice
|
| > The only thing worse than no documentation is wrong
| documentation
|
| Yeah, that was the exact problem. One was a startup and when
| I joined it was all mostly up-to-date so it was great! But by
| the time I left (after 2 major migrations) most of it was out
| of date and a nightmare to find anything updated, any script
| that could still be run, etc.
| CharlieDigital wrote:
| > Imagine working on a codebase where 80% of the code was
| unused or commented out
|
| That's not documentation; that's code.
| phkahler wrote:
| >> That's not documentation; that's code.
|
| It's an analogy to make the point - we delete old code that's
| not relevant any more. Imagine reading documentation where 80
| percent of it is no longer relevant but is kept around "just
| in case".
| [deleted]
| atoav wrote:
| I really like the way documentation works in Rust: You
| basically write markdown in a special type of comment over the
| module, function, datatype or method you wanna document and
| then you can convert that into documentation automatically.
|
| Even better: if you have examples in code blocks in these
| docstrings per default they get tested as well, so if you don't
| update them, the tests will fail and you will notice.
|
| In my eyes one of _the_ biggest problems with keeping
| documentation up to date is that over time the mapping between
| the piece of code you are documenting and the place where you
| find it in the documentation becomes more complex, to a point
| where missing something is not unlikely. Rust 's documentation-
| in-code-approach addresses this problem neatly.
| barrkel wrote:
| This is API reference documentation. What you're missing is
| conceptual documentation and use case examples.
|
| Conceptual documentation, the big picture, is important to
| convey the mental model implemented by an API. In
| applications, you can generally infer it from using the app,
| but it's not always easy, and it's indirect.
|
| Use case examples string together multiple APIs, multiple
| domain objects, to achieve a high level business objective.
| When working on a project, you can sometimes get away without
| this - the existing code can be example enough to copy. You
| can end up with cargo culting, people copying things without
| understanding why. But if you have an API for third-party
| use, which needs documenting, you need to have either a well-
| seeded set of open source users, or a great set of examples.
| Gwypaas wrote:
| Rustdoc supports conceptual documentation quite well,
| including testing the example code. A specialized page is
| better, but the pareto principle applies.
|
| See the Clap documentation:
|
| https://docs.rs/clap/latest/clap/
| paddy_m wrote:
| I often call this narrative documentation. It's the
| antidote to Chesterton's Fence and explains the thinking of
| the programmer who created the thing. How did that
| programmer expect people to use their tool.
| hitchstory wrote:
| I built a testing library on top of pytest based upon the
| idea of doing this mapping at an application level instead of
| a method/function/class level.
|
| If you write tests in a strongly typed, non-turing complete
| markup (in this case, StrictYAML), you can then use it with a
| template and test artefacts (e.g. app screenshots) to
| generate readable how-to/tutorial docs which are guaranteed
| to stay up to date.
|
| https://github.com/hitchdev/hitchstory
|
| This isn't a new idea, but I find that people are often
| skeptical because there's a history of people getting their
| fingers burned by Gherkin's language design or YAML's weak
| typing (both of which are completely valid).
| cjfd wrote:
| I don't have experience with this in Rust but have come to
| passionately hate this kind of documentation in other
| language. I think all of pydoc, javadoc and, doxygen are all
| garbage. If one could apply them sensibly it would not be so
| much of a problem but then you have documentation nazis who
| force you to document every method and every parameter. This
| leads to hightly enlightening prose documentation that the
| get_height method "gets the height", and that its return
| value is the height. A more high level problem with this is
| that you get documentation that is just as fragmented as the
| code and where the high level usage of things is not
| explained at all. Also it clutters the code with many highly
| trivial remarks.
| c00lio wrote:
| I am a documentation nazi. I hate it when people skip over
| documentation because something is obvious or trivial to
| them. Stuff isn't obvious or trivial to people who have to
| use your code.
|
| get_height gets which height, outer or inner? Are there
| error values, e.g. 0 as "don't know any height"? Does it
| have side effects? Is it a stable and reliable part of the
| API or bound to change soon? Is it thread safe? Will it
| change any of its parameters? Who deallocates the return
| value? Do you need to hold a lock somwhere?
|
| Of course it might be a good idea to group together
| get_height, get_width, get_diagonal and get_depth if the
| above is all the same for those. But having no
| documentation just because you think it is trivial that
| get_height gets some height from somewhere just means that
| you are sloppy and didn't think of all of the above. So
| your code shouldn't be touched with a 10-foot-pole imho.
|
| My solution, which I personally hate but know of no
| alternative to, is a documentation template for each
| function asking the above questions (depending on runtime
| and language of course) that I give people to fill in.
| Until they learn...
| makeitdouble wrote:
| > get_height gets which height, outer or inner? Are there
| error values, e.g. 0 as "don't know any height"? Does it
| have side effects?
|
| In my experience, if your documentation covers all these
| aspects it's guaranteed to be either wrong, misleading,
| or out of date on any of these details, and you better
| read the actual code to be sure.
|
| In particular, the answer will often be "it depends on
| what the rest of the system does". Perhaps it delegates
| the actual calculation to an API, and this doc won't
| change when the API changes in a _mostly_ compatible way.
|
| I mean, even with the best efforts given, code has bugs,
| words are vague, there's no way you should trust the dev
| who wrote the code to properly convey what it actually
| does.
| dacryn wrote:
| I don't agree with this answer. I fully agree that
| documentation is important, needs to be correct and
| maintained. However, I do stand by the original poster
| saying that it is often a bad idea to enfroce javadoc
| style comments to autogenerate documentation. This often
| leads to low quality documentation.
|
| Like you say, get_height is a trivial function, but still
| requires attention. Enforcing in-code docs is not going
| to help to have higher quality docs, quite the contrary.
| You often get low effort stuff, just to make the code
| checker happy.
|
| And if you put in a peer review process to validate the
| in-code comment, it loses all power because you might as
| well use that step for decent documentation. get_height
| should be documented in a logical place, where it makes
| sense indeed, like grouped with get_width. But now you
| have the logical place to put your documentation, and the
| forced javadoc comment. That's double work, and one of
| them will be bad quality as a result of it.
|
| Nobody is arguing for no documentation, but I am arguing
| for avoiding javadoc enforcements. My solution is much
| simpler: have a documentation check as part of the peer
| review process. Sure, have a template for the
| documentation, but don't make it strict. Ours is simple:
| all juniors are on documentation peer review as part of
| their onboarding. If they don't get it, it needs to be
| fixed.
|
| Our peer review process is quite simple: is the
| documentation adapted, is there a relevant unit test (we
| actually have low UT coverage, we only do them for
| critical code and as part of bug fixing, so enforced
| frameworks make no sense for us), and naturally is the
| code quality itself ok
|
| But many companies don't do those, yeah well thats how
| you get shit.
| frde wrote:
| Most of what you described as needing documentation could
| be expressed as code (mixing multiple languages here to
| express the point more clearly)
|
| const fn get_outer_height() -> Result<SomeErrorType,
| WeakReference<Number>>
|
| - `const` makes it clear this doesn't mutate
|
| - the function name says exactly what it does
|
| - The return type makes it clear it can return an error
|
| - The return value is typed in a way that makes it clear
| what the ownership is
|
| Throw in a language like Rust that gives guarantees about
| thread safety and now the only thing left is if the API
| is stable or not. Which I would argue doesn't matter much
| at all since people will still end up depending on it
| regardless of the comment saying "This API might not be
| stable"
|
| And the best part? My definition will never get outdated.
| If the assumptions change, the definition will also need
| to change (well, except for maybe the name)
| c00lio wrote:
| You are absolutely right, and one should prefer languages
| that can give such guarantees wherever possible.
|
| But often one doesn't have a choice. People still write
| software in inferior languages such as Javascript or
| Python, where you cannot even be sure about a return or
| parameter data type.
| kristiandupont wrote:
| It's true that there can be gotcha's in code which should
| be documented, but I don't think forcing a template on
| people is the solution. In fact, I wouldn't expect people
| to be better at documenting them with that in place.
| c00lio wrote:
| Well, yes, you need to have manual or automatic checks
| for the presence of the template, and the correctness of
| the contents is often uncheckable by automated tests. But
| if things break and e.g. the filled-in documentation
| template incorrectly said "thread-safe: yes", it will be
| very easy to 'git blame' the culprit. That way you can at
| least slowly weed out the sloppy documenters, but I admit
| that this is tedious.
|
| And, yes, I don't like this either and would like a
| better solution. But so far I didn't get any viable
| suggestions.
| II2II wrote:
| To add to what you're saying:
|
| Quite often something is not obvious or trivial to
| someone who is examining a piece of code or using a
| library for the first time because it assumes the person
| already understands the context.
|
| An example of what I mean: perhaps it is because I have a
| background in the sciences, but I assume that most
| properties have units. A property such as height
| certainly does have units. So is get_height() returning
| the height in pixels, inches, meters, or something else?
| I have also been bitten by graphics libraries that
| measure distances in unexpected (to me) way. Is the
| radius of the arc with line thickness 'n' using the
| inside radius, outside radius, center line, or something
| else? The person writing the original code may think the
| developer using their code down the road can test
| different assumptions, yet the reality is the number of
| combinations to test will rarely be trivial (and that is
| assuming they identify the correct parameters to test).
|
| It's at the point where I refuse to even consider using
| libraries that leave out documentation for obvious
| things. Even comments like "gets the height" raises red
| flags since it is a demonstration that the author did not
| put any thought into what they are documenting.
| marcosdumay wrote:
| I am firmly on the opinion that every bit of public
| interface should get a documentation string.
|
| You say "gets the height" is trivial, but that text tells
| not only what the function does, but also that the author
| couldn't think of anything else important to say. This is
| very different from no text at all, where you can't be
| certain if the author even thought about it.
|
| IMO, enforcing an internal structure (AKA "you must
| document each parameter and the return value") is counter-
| productive, but enforcing the existence of the comment is
| very productive.
|
| > Also it clutters the code with many highly trivial
| remarks.
|
| I'd say that it "clutters" the code with markers for public
| elements and hard to understand ones. Those are actually
| valuable, and not clutter at all.
|
| Anyway, if those markers are a large share of your lines,
| you may need to rethink your architecture. It's usually not
| valuable to have a lot of interface for trivial things.
| Karrot_Kream wrote:
| Yeah this is why I love literate programming. Being able to
| read a program with "narration" is so much nicer than just
| reading documentation piecemeal. Maintaining literate
| programs though is a quite difficult because you have to
| figure out where new code or changes fit in the overall
| narrative. I have a scraper I wrote in literate style and I
| only have to change it yearly. Each year I forget what I
| wrote and then I reread the program and make the necessary
| changes.
| bayindirh wrote:
| Literate programming is great until your code base
| becomes unwieldy. Then you need a README.md file which
| acts like a pointer to the correct entry points.
|
| Then as the code grows, you need to document the
| architecture, add small gotchas, etc.
|
| At the end of the day, documentation wins.
| hahnbee wrote:
| I'm the CTO of Mintlify - we help other startups create their
| developer-facing documentation. We've been working in the
| documentation space for a little over a year now and I spend a
| lot of time thinking about documentation. I completely agree
| here.
|
| Documentation is such a hard problem to "solve" if you're a
| fast-moving startup. You need a mixture of creating a
| documentation-first culture and acknowledging that
| documentation is difficult to maintain. Ultimately you end up
| creating processes to help people document their intent,
| decisions and the mission critical information.
|
| There is also such a large range of types of documentation -
| varying scale from internal to external and technical to non-
| technical.
|
| We started by creating https://writer.mintlify.com/ which
| really resonated with developers because it made it easier to
| write documentation, but it only helped generate documentation
| that was highly technical and close to the code. We decided to
| stay in the documentation space but try another vector and so
| now we're taking a crack at public-facing documentation - which
| in my opinion is a different can of worms than internal
| documentation. However as I'm building and growing my startup
| and I find myself continuously playing whack-a-mole and I
| definitely hope that we can build the foundation and expand to
| make it easier to maintain all different types of
| documentation.
| kristiandupont wrote:
| I'm trying your extension out and it looks promising.
|
| A tiny bit of feedback: the shortcut key is defined in
| settings, not keybindings which seems wrong? Also, the
| default is to override cmd+. which is an important shortcut
| already..
| SnoopDougDoug wrote:
| I've been creating software developer docs for decades. Most
| contain the following content:
|
| About X Installing and configuring X Using X X Reference
|
| Typically developer docs are created from the bottom up. The devs
| create the preliminary reference docs using special comments in
| their code.
|
| Once they are through, I go through their comments and wordsmith
| them.
|
| After the reference topics are written, I start adding a "guide"
| section. I like to call this the "How-to" section, which answers
| questions like: * How do I create Y * How can I ... and so on.
|
| I try to answer two classes of questions: * Tasks that everyone
| does (create a client, ...) * Tasks that flummox a lot of people
| (talk to the folks manning the help desk)
|
| Once I'm happy with these task-based topics, I'll create a simple
| "Hello world" tutorial. This topic helps the user know that
| they've successfully installed and configured the software.
|
| Finally I'll write the installation and configuration section.
|
| It's possible to work on more than one section at a time. In
| fact, I typically write a bunch of sample code to try out ideas
| before I create the guide and tutorial. If possible, I'll tidy up
| these code snippets and add them to the docs. Developers always
| ask for more code examples.
|
| And speaking of which, if you do create a code example, please
| create an accompanying unit test. Don't make your users find out
| that version 1.1 broke your code example. That's your job.
|
| doug in Seattle
| GuB-42 wrote:
| The thing that seems to come out of all these conversations is to
| treat documentation as UI/UX.
|
| Maybe the problem is that it is treated as a secondary activity
| for developers, when it should be treated as a primary activity
| for writers.
|
| We don't expect developers to be good at graphic design and even
| UI/UX design. In fact we should expect them to be terrible at it.
| A developer looks at the product from the inside, he sees
| classes, databases schemas, etc... not the way an end user will
| look at it. It means he will be biased into having a UI match the
| code structure and not the user workflow. There is a reason UI/UX
| designer is a job title, it is not a secondary activity for
| coders. Some can do both, but it is a different job.
|
| Documentation could be treated the same way. Have people
| specialized in writing documentation. People who are actually
| good writers. I have seen it happen occasionally, and let me tell
| you, when you put a good writer (coding skills optional) in
| charge of writing documentation, the difference is night and day.
| Just as how better your UI will be when done by a good UI
| designer, and by a good UI designer, I mean someone who actually
| designs for usability, not someone who just tries to make
| something that looks cool for sales presentation, as it is too
| often the case for consumer apps today.
| makeitdouble wrote:
| That angle is very good.
|
| To me what's missing in many of these discussions is the
| cost/result calculation, how much effect is expected from
| "documentation". Thinking of it as an UX/UI could help put it
| more in terms of what time is spend by which user to achieve
| which specific task.
|
| If specific use cases can be described, what needs to be
| written down becomes a lot more obvious and it can be done way
| more efficiently than just blindly "documenting" a system.
| bjornasm wrote:
| Along these lines it was a shocking experience for me to to to
| use FastAI. Their documentation is incredibly poor (imo).
| paddy_m wrote:
| I often find that trying to document code or a product forces me
| to rethink how I wrote it. Sometimes it's easier to change the
| code to make the concept simple to grok, then to write the
| documentation for the hard to grok concept. This is a very good
| thing.
|
| Companies in general should do much more writing. Writing forces
| you to think in ways that coding doesn't. For me it's much easier
| to spot a poorly thought out argument then a bug in code (not a 1
| for 1 comparison).
___________________________________________________________________
(page generated 2023-06-12 23:03 UTC)