[HN Gopher] The tree-based approach to organizing documentation ...
___________________________________________________________________
The tree-based approach to organizing documentation sucks
Author : cgenschwap
Score : 73 points
Date : 2021-03-10 17:47 UTC (5 hours ago)
(HTM) web link (www.worldofbs.com)
(TXT) w3m dump (www.worldofbs.com)
| jfax wrote:
| >graph based
|
| Is it really too uncool to say "hypertext" these days? That's all
| I'm understanding here. Write docs in hypertext. Otherwise I
| agree.
| tdrgabi wrote:
| Isn't google providing a lot of heavy lifting for wikipedia, by
| "figuring out" what I want and taking me there.
|
| Wiki just on itself, where you need to browse inside to get
| where you need won't work. Now you need to find the right node
| in the graph that connects to your information.
|
| I feel the same way about Stack Overflow. I rarely search for
| the answer to my question inside SO, instead google takes me to
| the relevant page.
|
| So what companies seem to need is documentation in any format,
| hierarchy or graph, plus a really, really good search engine
| over it.
| lpapez wrote:
| Hard agree. Finding information on SO has always been much
| easier for me by asking Google to search there than by using
| the local search bad.
| rakoo wrote:
| Links aren't used for searching, they're used for expanding
| knowledge on a topic you're already investigating. A personal
| example: I had to update our metrics infrastructure so I read
| the existing documentation to understand the way it is done
| today, and there was a link to our metrics naming spec. I
| wasn't going to need it but it was still interesting to
| understand what the conventions are and potentially updating
| them.
|
| We're using the Atlassian wiki, for which I find search to be
| very bad so we kind of _have_ to work with links.
| josephorjoe wrote:
| Documentation sucks where no one gets promoted for writing great
| documentation.
| prepend wrote:
| I think it's actually negative incentive as if you document
| stuff, you might get questions about it.
|
| I've seen the "no documentation = job security" anti pattern
| for decades. But recently I've seen the "if I write something
| down I can be questioned better by more people so I can lay low
| by never describing what I'm doing how how you can reuse my
| libraries and methods."
|
| It's a weird situation where people get promoted for "doing
| stuff" and not for "others doing stuff with my stuff."
| MaanuAir wrote:
| I like writing good documentation.
|
| I've never seen any incentive for that, apart from colleagues'
| thanks, which is not especially converted into promotion.
| canistr wrote:
| The author's comparison of Tree/Graph approach doesn't flow
| logically from the discussion about ad-hoc documentation.
| Searching Slack for answers has become more valuable to me
| because of this ad-hoc nature.
|
| StackOverflow is arguably more ad-hoc than a pure Wiki approach.
| I can already add links inside Google Docs. So the graph isn't
| the solution that solves this.
| dkarl wrote:
| I found organizing and finding documentation to be a huge problem
| ten years ago, not so much now with wikis having decent search.
| The biggest problem remaining is that it's simply hard to write
| good documentation, much harder than providing ad-hoc help in
| person or over Slack.
|
| The reason is that every time you provide an ad-hoc explanation
| of how something works, you have a concrete context: a person,
| what they're trying to accomplish, and their understanding. You
| also have the opportunity to correct course as the person
| provides immediate feedback in the form of questions and
| comments. You have a high probability of eventually navigating to
| positive feedback and a thank-you at the end.
|
| Writing documentation for an abstract audience is much, much
| harder, and as a result, you will likely hear a lot of negative
| feedback.
|
| You think you've documented something really thoroughly, and then
| you hear that it took a recent hire two days to get through it
| instead of two hours. You start hearing, "This production
| troubleshooting task was supposed to be documented, but the new
| person said they had to figure most of it out for themself." WTF?
| What is "most of it?" You wrote down everything. So you talk to
| the new person and find out that even though they're a mid-level
| engineer, they only know Java and have never heard of jq, so for
| the part that requires pulling some data out of a complicated API
| response and feeding it to a different API, they wrote a
| 1000-line Java program complete with tests. You also find out
| that nobody told them how to make read-only calls to production
| APIs for troubleshooting purposes (you probably should have
| linked that info from your documentation) and oh my god in their
| quest to do this they somehow got their hands on the production
| API key used by one of the services. Equally horrifying and
| impressive. So that's what they've been doing for the last two
| days, because your documentation didn't anticipate the questions
| they had.
|
| All of that would have become apparent in five minutes on Slack,
| and it could have been cleared up with a couple of links and
| examples, but you didn't anticipate any of it when you wrote the
| documentation. And that's because documentation is hard.
| [deleted]
| 1123581321 wrote:
| Users like outline trees. Trees communicate a lot more
| information about what the project does and what systems or
| features support what.
|
| Wiki linking, in that case, is just an alternative way to
| duplicate the content of a page on the tree. Other methods
| include redirects and using software that can symlink individual
| blocks of text to keep them in sync.
|
| As to why documentation is bad, it's because people close to a
| project are not in a good position to communicate about it.
| Absent a large, self-documenting community, the best solution is
| to either have documentation be done by an employee who is a
| power user or customer of the system, who writes well, or by
| taking developers off production duty to do nothing but provide
| support to users and structure them into general answers and
| explanations.
| [deleted]
| lhorie wrote:
| I think of documentation as my little secret superpower. It makes
| one more productive (i.e. one doesn't need to keep getting
| interrupted to be asked the same question yet again), it makes
| others more productive (they can unblock themselves and use the
| docs to supplement their little corner of tribal knowledge), and
| good docs allows one to offload knowledge of specifics from one's
| brain such that just searching for a keyword is sufficient to
| recall all the nitty-gritty context one needs to fix whatever is
| the issue at hand.
|
| My general approach is: if a question gets answered in chat, also
| add it to docs. Personally I dump each question as a markdown
| header + paragraphs (typically with an error message or uniquely
| identifiable string in the header), using a FAQ format under
| whichever page makes the most sense. Then it's easy to find the
| section w/ the search widget (we use js-search on a next.js SSG
| site) and it's easy to link to the specific header. Then, the
| next time the question gets posted on chat, just open docs,
| search, copy permalink, paste, done.
|
| I agree that making full-fledged, truly useful docs is a lot of
| work, but you'd also be surprised how much you can get out of
| relatively little work.
| majkinetor wrote:
| I have similar approach. If I can't send you think link on
| Slack, its not good enough. If you don't understand, I update
| the docs and send you the link/diff again.
| mvanga wrote:
| The graph approach (e.g. Wikipedia) is pretty much useless
| without a search engine (e.g. Google) directing you to the first
| useful node in the graph. When is the last time you just jumped
| onto the Wikipedia homepage and found your way to the information
| you wanted?
|
| So once you accept that a graph structure is useless without
| powerful search behind it, the advantages of the tree approach
| are more obvious: it provides a basic search mechanism through
| hierarchy, and still allows for a graph approach (via linking and
| duplication of content in multiple categories).
|
| Also, maintaining documentation sucks. So there's that...
| brundolf wrote:
| Is "powerful search" really necessary? I feel like you could
| get by with simple keyword-matching and maybe browse-by-tag
| pwdisswordfish0 wrote:
| MDN uses a hierarchical structure--a mistake that should have
| been corrected 10 years ago--and it's awful.
|
| > When is the last time you just jumped onto the Wikipedia
| homepage and found your way to the information you wanted?
|
| Literally every day. If you haven't done this, the only
| explanation is that you haven't tried. Wikipedia's built-in
| search is fine (and also completely unnecessary more often than
| not, since you can guess most page titles _and their URLs_ ).
| In fact, I've had my browser's default search engine set to
| Wikipedia for probably 10 years now. If I want to Google
| something, it's either because I've already hit the Wikipedia
| article and it was wanting, or it's because I'm looking for
| something different in nature.
|
| The claim that Wikipedia is junk without Google is itself junk.
| gomox wrote:
| I haven't found a good enterprise (for SME's) wiki. Mediawiki is
| not really usable out of the box without significant work.
|
| Obvious stuff is hard to set up, e.g. private wiki with SSO.
| prepend wrote:
| I had the same problem and tried a bunch of stuff (mediawiki,
| confluence, GitHub wiki, gitlab wiki, shared drive, Wordpress,
| SharePoint) and currently just use GitLab pages because the
| fork/merge flow for markdown was easier than trying to grant
| access and moderate a wiki.
|
| It's still easy to solicit edits, but the issue/question flow
| is helpful, and have some review process seems to help. Lots of
| people struggle with git mental models, even using the built in
| browser IDE in GitLab and GitHub. But most engineers seem to be
| able to handle.
| pwdisswordfish0 wrote:
| Conjecture: almost every belief that your wiki needs support
| for ACLs and needs to be moderated (for any reason other than
| spam) is a belief that's wrong from the start. (And it should
| be a criminal offense the way that GitHub and GitLab to have
| corrupted the word "wiki" to be understood to include PR- and
| review-based workflows centered around big collections of
| offline source files--the very practice that the wiki was
| created in reaction to, as a means to solve the problems
| inherent to that workflow.)
| mikewarot wrote:
| Autogenerated documentation really sucks as well, no matter if it
| is tree, graph, or wiki based. (Which are all the same thing, in
| the end)
|
| The bane of my existence in the last 24 hours is a typical
| example: https://www.freepascal.org/docs-
| html/current/rtl/fgl/tfpgmap...
|
| There are links that go places, but nothing anywhere actually
| shows working code examples, or even non-working fragments.
|
| One of the reasons actual civilians were able to write their own
| programs back in the 1980s was that Turbo Pascal, and Visual
| Basic had decent manuals, and there were plenty of "dummies"
| guides as supplements.
|
| Documentation should include working example code for each and
| every library, function and property supplied.
|
| /End old man rant
| jrochkind1 wrote:
| engineers don't hate _writing_ documentation, they hate
| _maintaining_ it -- even more than they hate maintaining code,
| which they already don 't love even though they love writing it.
|
| The OP actually tells that story exactly. They love writing
| answers in slack precisely because they are ephemeral and
| targetted at a specific immediate need (which also makes it a lot
| easier than writing general-purpose documentation btw). But the
| persistent documentation "just decayed and eventually nobody used
| it." Exactly.
|
| It's possible the right tools can make it easier to maintain (and
| thereby less likely to go out of date), but I don't think just
| simply taking a graph approach is sufficient or a very
| significant part of it. I'm not sure what that would be -- one
| obvious answer is tools that generate docs from code or otherwise
| tie it to code in such a way that when the code changes the docs
| are forced to change. But while that makes sense, every attempt
| at this I have seen results in disastrously unfriendly
| documentation (see eg "relish").
|
| Other approaches are just to capture all that "answer the
| ephemeral question" documentation that is happening anyway in a
| way that makes it persistent and more easily searchable. A sort
| of "knowledge base" approach. (which, true, isn't tree-based).
| Some of the answers will be out of date when you find them later,
| but that is expected which somehow makes it less disruptive, and
| it's still better than nothing.
| sjg007 wrote:
| Here's your billion dollar slack startup.. create a way to get
| that slack knowledge into your official documentation.
| tln wrote:
| I like markdown inside the code repo for the precise reason
| that it is easy to maintain! Also it easy to review ("Hey, this
| PR should update docs/Testing.md"), and easy to be in sync with
| what's deployed.
|
| At $WORK I've got our repos hooked up to Slab, where the wiki
| style docs also go, so any search in Slab finds the markdown
| files as well.
|
| And WRT slack, many tools including Slab let you use /slash
| commands to find answers. So in response to a question, you can
| do a /slab search, and maybe even /slab create to start a stub
| for a topic.
| prepend wrote:
| Sorry, what's Slab? I couldn't figure it out by googling
| "slab source."
| sfg wrote:
| > _Slab_
|
| I'm guessing, it is https://slab.com/ ("The knowledge base
| that democratizes knowledge"), which I discovered by
| searching for "Slab for Slack".
| tln wrote:
| Thanks, that's indeed the tool. Sorry I should have
| linked that.
| prepend wrote:
| Thanks. Comically googling for "slab" didn't show
| slab.com, although it does now.
| cgenschwap wrote:
| You are right that maintaining documentation tends to be the
| sticking point. The main difference between a graph approach
| versus a tree approach is the _amount of effort_ required to
| maintain. If the documentation is incorrect in a tree-based
| system, say to the point where it is in the wrong place in the
| hierarchy, it requires a significant amount of effort to fix
| and maintain. In a graph-based approach it is easier to fix the
| areas that need to be fixed -- the maintenance burden is lower.
|
| It is also easier to phase out certain documentation, but
| writing newer, more correct documentation and deprecating the
| old. Of course this is still possible with a tree-based
| solution, but there is more flexibility in a graph-based
| approach.
| julianlam wrote:
| I personally find auto-generated documentation based off of
| code is just awful, unless all you're looking for is the
| function signature and/or type. Every time I see auto-generated
| docs, I back out immediately.
|
| The problem I see here is that writing docs when writing code
| is a different kind of mental activity, and requires some
| amount of context switching which developers by-and-large are
| loathe to do.
|
| At least for NodeBB's API[1], we wanted documentation that kept
| up with changes, so we put in the hours to get a handwritten
| OpenAPI v3 spec written, and added a rigorous test suite[2]
| that not only checked syntax, but ensured that all routes
| defined actually returned a response with the expected schema.
|
| We extended this later on to do the reverse; to check the
| mounted routes and ensure it is defined in the spec.
|
| It's a pain in the butt when your feature gets pushed and
| immediately fails API tests, but the tradeoff of having
| guaranteed up-to-date docs is well worth it.
|
| [1] https://docs.nodebb.org/api/ [2]
| https://github.com/NodeBB/NodeBB/blob/master/test/api.js
| throwanem wrote:
| This is good advice, but I'm actually a lot more interested in
| the "four types of documentation" that it links to:
| https://documentation.divio.com/
|
| That seems like a super useful categorization, and I intend to
| use it to inform my own efforts going forward - the first thing I
| noticed when I looked at this typology was that I generally try
| to write _all_ of these, and probably the primary barrier to
| utility in the documentation that I write is that I haven 't
| previously had a good sense of how to separate them out.
| ohuf wrote:
| I don't get the author's dislike of Confluence, when it is just a
| different representation of.a Wiki. I actually like the way
| Confluence implements draw.io so I can quickly scribble an
| architecture or A flow.
|
| What am I missing here?
| waiseristy wrote:
| What's missing here is the effectiveness of the tools search
| functionality. Confluence does this wonderful thing where, even
| if you quote the search terms, it will just interpret what it
| thinks you were trying to search for. You know of a doc that has
| a very distinct keyword in it? Perhaps "runnable" or something
| like that? Well too bad, now you have to sift through 500 pages
| of results for run, running, ran, etc.
|
| https://jira.atlassian.com/browse/CONFSERVER-14910
|
| I will almost always shove a bunch of distinct keywords at the
| bottom of my docs so future searchers can find useful
| information. This finding information through a log(n) tree
| search is total bupkis. Relying on others to organize information
| in the same mental model as you is totally unrealistic.
| sjg007 wrote:
| I agree confluence is terrible. The tags thing is kind of OK.
| Gmail fwiw has a similar problem.
| readthenotes1 wrote:
| The tree-based approach works better with paper documents
| area51org wrote:
| It's all and none of these things. The single biggest problem
| with documentation is that _it is written by people who are not
| imagining themselves as the USERS of the software_. Typical docs
| are descriptions of the software, like you 'd describe an
| elephant: here's the trunk, these are what the feet look like.
| Want to work with an elephant? You're on your own.
| ebiester wrote:
| I think the article is talking about internal documentation
| rather that user-facing documentation.
| MaxBarraclough wrote:
| Related to this: understanding the various types of
| documentation, and using them all appropriately.
|
| I highly recommend Daniele Procida's talk about this, [0] and the
| accompanying web page [1]. He gives a useful taxonomy of the 4
| kinds of documentation. Through the power of Unicode:
| +--------------------------+-------------------------+ /\
| | Tutorials | How-to Guide | ||
| Practical | (Learning-oriented) | (Problem-
| oriented) | ||
| +--------------------------+-------------------------+ |
| Discussions | Reference | || |
| (Understanding-oriented) | (Information-oriented) | ||
| Theoretical
| +--------------------------+-------------------------+ \/
| <=== Useful for study Useful for coding ===>
|
| [0] https://youtu.be/t4vKPhjcMZg?t=160 (that will take you to the
| start of the talk proper)
|
| [1] https://documentation.divio.com/
|
| _edit_ Didn 't spot the link to [1] at the bottom of the article
| :P
| abraxas wrote:
| This was solved in 1995 with WikiWikiWeb. Not sure why the bi
| directional links did not become more of a standard.
| majkinetor wrote:
| This view is too much simplified. If docs were tree vs graph
| problem we would probably have at least some orgs doing it right,
| while there are literarily almost zero.
|
| Just few of the missing aspects:
|
| 1. Narrative style. You can't do ad hoc whatever wherever and
| call it a day. Most people don't have it and many are quite
| illiterate IMO. You need to practice this and most engineers
| don't like that. Hell, even most seniors don't like writing
| tickets IME which take almost the same time as putting garbage on
| Slack. I created templates on both GH and GL and almost nobody
| uses them even tho you don't need to think about anything but
| follow few rules.
|
| 2. Its quite hard to know what level of detail to put in
| documentation. You need a lot of experience for this - put to
| much, and it gets quickly outdated, put too little, and it
| doesn't convey much. Good documentation exists on multiple levels
| - as bunch of markup files "on the spot", as formal hi and low
| level documentation and also those are usually affecting
| different target groups so you actually need to design docs.
| Cross references are absolutely essential, the docs need to be
| 100% hyperlinked and in static site format (no big Word or PDF
| docs really, that should exist only as an export variant). But
| you also need a tree, because you can just say to people "here is
| a bunch of docs" just surf around, and good luck". So both tree
| and graph are required at the same time.
|
| 3. Documentation is a service. It has source code, build
| procedure, automatic link checking, versions, exports to bunch of
| formats, crosslinks, variables, macros, configuration for
| different environments, abbreviations, definitions, automation,
| includes and what not... Its quite hard to get it right. After
| years of struggle on different projects I finally created my own
| stuff [1] by bundling many different tools and configs in docker
| container that I use on all projects, for docs spanning 50-500
| pages. I maintain that for years now, constantly (so yeah, its a
| job).
|
| I am always interested in this as I write tones of docs as a part
| of system design role. If you have some good ideas to offer,
| don't hesitate.
|
| [1]: https://github.com/majkinetor/mm-docs-template
| buescher wrote:
| If the FAANG companies started recruiting on ability to
| communicate in spoken and written English, there'd be a cottage
| industry in making sure developers weren't functionally
| illiterate.
| endymi0n wrote:
| I'll let you in on the biggest unsolved problem in computer
| science. And no, despite the joke it's neither cache
| invalidation, naming, concurrency nor off-by-one errors. It's not
| even handling dependencies.
|
| It's knowledge transfer.
|
| I haven't seen any bigger problem until now and I haven't seen
| anything that comes close to a solution. Even though, I'm pretty
| sure of what is not a solution and that is (mid-level)
| documentation.
|
| Before I go taking that back a notch, let me clarify what I mean
| with that, as I've seen the cycle numerous times and have been at
| several of those points myself.
|
| "This is a mess, I don't understand anything... this isn't
| logical. We need to document everything!
|
| -> Sorry for that bug, I read your docs, but they were outdated.
|
| -> Sorry for that bug, I didn't even bother to read the docs,
| because most seemed outdated.
|
| -> We'll need to make sure the docs stay current, let's hire a
| technical writer / wiki gardener / wtf and introduce a process in
| our "Definition of Done (tm)" so it's all up to date
|
| -> (Actual Development mostly halted by now)
|
| -> Hey, welcome! Oh by the way, before your first commit, please
| read these 700 pages so we're sure you know what you're doing.
|
| Talented Junior Dev: !!! -- Here's my resignation."
|
| The clear exceptions to this casual observation of mine are
| implicit and high-level documentation.
|
| Implicit includes:
|
| - self-documenting types and code ("Ronseal Code"):
| https://web.archive.org/web/20170426021541/https://peternixe...
|
| - self-documenting gRPC and Swagger API schema
|
| - self-documenting constraints
|
| - Architecture and Schema diagrams
|
| - Specs and Design Docs
|
| - READMEs
|
| There's only a very limited case where mid-level docs make sense:
|
| - lots of consumers (public & commercial code)
|
| - stable systems with high fluctuation operations
|
| Other than that, this kind of documentation rots far too fast to
| have much net benefit at a high feature pace.
|
| The only tools that I've consistently seen work so far for
| knowledge transfer are simply hiring good and communicative
| people with a learning mindset, keeping attrition low by keeping
| them happy and productive, intro sessions, code reviews and
| growing reasonably slow while leveraging junior/senior (as in
| tenure) pairings for new projects.
|
| No kind of documentation in the world replaces the mental models
| of the people who architected a piece of software.
|
| Old guy rant end.
| more_corn wrote:
| The style of the content is often more important than the
| structure.
|
| I've invented a documentation style I call "Notes for Nerds" It
| consists of the specific notes you make for yourself if you need
| to re-implement something complicated you've done.
|
| It's example driven, very specific and includes only such
| verbiage as necessary to contextualize the specific technical
| commands or code.
|
| I invented it because I found at Google that the best
| documentation was always the rough first pass stuff before it got
| prettied up. I specifically searched for deprecated documentation
| because it covered the technical exploration of the project
| before the final gloss was applied. Compare this to Google's
| public documentation if you want to throw up in your mouth a
| little bit.
|
| Notes for Nerds style works smashingly. I hereby grant the reader
| the right to re-implement my idea anywhere you like.
|
| Also, don't use Confluence. It is everything bad and wrong about
| a documentation tool. If Notion had a ticket system they would
| kill Atlassian overnight.
| loopz wrote:
| Title, links, short description and actual copy-paste go a long
| way. However, it won't dazzle execs.
| pydry wrote:
| I think the author is missing a key part of why developers often
| don't like writing documentation but do like answering questions:
| replacement value.
|
| A developer's compensation is based upon their perceived value
| (how much it seems like they are needed) and replacement value
| (how much would it cost to replace them).
|
| A developer that answers questions gets a reputation for
| helpfulness - this increases their perceived value. Another
| person needing to go to them to ask questions increases their
| _replacement_ value too - the more they become the go to person
| for info, the clearer it is that the company would lose out if it
| replaced them.
|
| Written docs have almost the opposite effect. Writing amazing
| documentation doesn't tend to get you a reputation - mostly
| because it's so depersonalized (does anybody think about the
| person who wrote a quickstart guide?). It also decreases your
| replacement value - a fantastically documented project is a
| project that can be easily handed off to someone else.
|
| I really think that humans get a buzz out of being helpful, too,
| and you just don't get the feedback that gives you that buzz by
| writing pages in confluence or whatever. You will likely not even
| know who found it useful, whereas the dopamine hit you get when
| somebody asks you a question and you answer it and they click the
| "heart" button on your slack message is instantaneous.
| erikerikson wrote:
| There's another perspective to take on this. This sort of
| behavior you are describing locks you further and further into
| the role you are in right now, reducing the rate of which you
| grow and learn. It sets up by dynamic where the company is
| incentivized to keep you there.
|
| Another possibility is that you make yourself entirely
| removable or even just solve the problem so well that it no
| longer needs headcount. Instead of seeing people reaching out
| to you as satisfying a "I feel needed" emotion, you can see the
| need to have been reached out to as a tax that reduces the
| value you create.
|
| Businesses really like developers who reduce replacement costs,
| solve their problems, and enable others. They tend to put them
| on increasingly valuable and interesting problems.
| pydry wrote:
| I've worked with the kind of developers who try to gatekeep
| their knowledge and the systems they work with. I find that a
| few of the following conditions tend to hold:
|
| * They're not very good developers and not very smart and
| probably somewhat cognizant of that.
|
| * They're afraid of interviewing.
|
| * They're working in smaller markets (e.g. a town which has
| maybe just one or two companies that hire developers).
|
| * They're spending right up against their income or beyond it
| and are afraid of losing their job.
|
| If they hit all of these checkboxes then I reckon this
| behavior is almost guaranteed and getting potentially
| "redundancy inducing information" out of them will be like
| pulling teeth. They'll be busy _a lot_. Far too busy to talk
| to you. Their docs likely won 't be nonexistent (too
| obvious), but they will probably be deliberately obtuse.
|
| They're primarily concerned not with learning but with not
| losing their primary source of income and their time horizon
| shortens, much like it does for those stuck in a behavioral
| poverty trap https://www.sciencedirect.com/science/article/ab
| s/pii/S03043...
|
| Yes, this sort of behavior locks you further and further into
| the role you are in and is possibly self defeating, but it's
| entirely natural and fairly common.
| afarrell wrote:
| > whereas the dopamine hit you get
|
| But have you ever had a salesperson at the pub tell you about
| how much easier it is to close deals by pointing to the API
| integration tutorial you've written?
|
| Hands down, absolutely the proudest accomplishment of my
| career.
| ryangittins wrote:
| This is an interesting point! I do think there's another factor
| at play here, though: documentation goes stale.
|
| When you've been burned by stale documentation (or any tool)
| enough times, you can start to lose trust in it. When you lose
| trust in documentation, you second-guess it and often pursue a
| a live, fresh second opinion from another developer with more
| knowledge anyway.
| aequitas wrote:
| And that developer gets fatigued by constantly having to tell
| others to RTFM, because the documentation is up to date and
| comprehensive, he took his damn well time to make it so, if
| they just also took their time to read it, but instead they
| always ask him anyways or he has to point everything out and
| at a certain point they just don't care anymore.
| ryangittins wrote:
| It's very true. I think in reality it tends to be a mix--
| sometimes documentation goes stale, and sometimes people
| don't even bother reading it regardless of whether or not
| it's stale.
|
| Another large problem is developers not knowing what
| they're looking for. Documentation tends to solve the "how
| I do use this" question and not the "do we already have a
| solution for this" question.
|
| I'm still not sure how to solve the problem of discovery
| outside of telling people, "read the docs and hope that
| someday you'll remember the relevant bits when you need
| to."
| williesleg wrote:
| Yay H1B's!
| choeger wrote:
| Documentation sucks because nothing is used very often anymore.
| In the good old days (TM), software was used for much longer in
| pretty much the same shape. Think of GNU coreutils.
|
| In contrast, your API or your frontend code or your Amazon Lambda
| or your Microservice is quite likely not feature-complete, does
| some things that should be handled by a different component and
| was developed with exactly one use case in mind until it was
| "good enough". Thanks to scrum, no one cares about completeness,
| orthogonal design, or composition of smaller parts anymore. Hence
| documentation has only token value. Except, maybe, for end user
| documentation, but I am yet to encounter a "user story" that
| begins with "As a user, I want to do X, read how to do X in the
| documentation, follow the instructions and get the desired
| results."
| jimduk wrote:
| Agreed, and I would add pre-web well authored Microsoft help
| files/ hypertext were often really valuable and could be very
| well done. Also you could build them after the software was
| done, or before, as the spec in progress. Think msft help was
| one of the unsung heroes of their success. But if you have
| changing software Google/SO is much faster. (Disclaimer, used
| to work on 'performance support' systems late 90s, one of the
| points of focus was how do you help users keep improving their
| combined tool use, team performance and business understanding)
| erikerikson wrote:
| The integration work is what's hard. Just like it's easier to cut
| new code and harder to resolve conflicting needs in two existing
| systems. Cleaning up the mess of how two things have moved
| forward under different incentive systems and for different
| purposes, that's the nasty stuff and the hard work. The
| accumulated disynchrony is what makes documentation suck and
| reduces the value of referencing it which can be a death spiral
| when it thereby reduces the value of producing it.
|
| This article reminds me of the challenges of an object-oriented
| decomposition of a system. The solution being something like
| adding aspects (see AOP), relationship links with metadata, and,
| sure, adding a graph structure.
|
| However, I would suggest that reducing the space between a
| documentation system and the code base it is documenting is one
| of the deeply important missing pieces. What belongs on a
| distilled documentation page versus in the code is the spectrum.
| We have data formats listed in our documentation but those should
| be links to the schemas (and maybe examples) in our code base.
| ulisesrmzroche wrote:
| I don't know, I think wikis work great. It's just that writing
| docs is a lot of work, and like people mentioned here, info
| decays.
|
| People do without internal docs for the same reason they ship
| without tests, Pareto principle. And writing is hard work,
| especially if it's meant for other people to read.
|
| Cheap, good, and done. Pick 2.
|
| It's people who don't keep expectations realistic that wind up
| going crazy in this industry.
|
| If you want your company to keep nice internal docs, you can't be
| cheap. You'll have to extend deadlines. You have to tell people:
| I'll have to add another week for docs and such. Usually, it's
| not worth to even bring it up. Why rock the boat?
|
| There's also the question of how much value they bring, usually
| not much.
| [deleted]
| sergiotapia wrote:
| So what graph based system do you recommend?
| nickjj wrote:
| IMO documentation exploration can be solved with good search.
|
| Tailwind is a good example of this at
| https://tailwindcss.com/docs.
|
| The table of contents is worded pretty well but once you get past
| ground zero of using a tool being able to search for what you
| want becomes a quick way to find what you're looking for.
| Especially since the search is powered by Algolia, it's pretty
| good with full text search.
| roland35 wrote:
| It takes a lot of effort to write good documentation. If the
| documentation is too low-level you get the extreme of "this
| function adds 1 to x" type comments which don't really help. If
| the documentation is high-level, many important details can be
| left out.
|
| What I try to help support on my projects are higher-level block
| diagrams which show the relationships between major components.
| Hopefully that doesn't change too quickly! The lower level API
| should be generated straight from the code itself with a tool
| like swagger or doxygen if possible.
| amelius wrote:
| There's this quote by Linus torvalds: bad programmers worry
| about code, good programmers worry about data structures.
|
| This should be reflected in the documentation.
| andrewzah wrote:
| Our documentation sucks because it is time-consuming to do
| documentation properly.
|
| I am hoping to fix this by introducing Optic [0] to automatically
| handle generating API diffs.
|
| [0]: https://github.com/opticdev/optic
| RandallBrown wrote:
| Documentation doesn't suck because companies aren't using wikis
| right.
|
| Documentation sucks because it's hard/impossible to do well.
| Every change to the code can trigger cascading changes in
| documentation and there's no compiler to tell you which things
| need to change.
| joncp wrote:
| Exactly.
|
| If we can't even keep the README up to date, when that's in the
| same repo as the change, how on earth are we going to be
| disciplined enough to go update the docs.
|
| And the occurrence of the word "disciplined" hints at the real
| reason: it's a lot less fun to write docs than write code, so
| we don't unless we're forced to by circumstances or by
| management.
| CobsterLock wrote:
| dont most enterprise languages have built in docs that do a
| basic type check? I'm thinking of something like JavaDocs and
| MS Docs for C#, that at the very least have built in typing for
| explicit references to objects. But i do see the breakdown
| quickly happening when you informally reference concepts. I
| have been trying to push for getting as much documentation
| inside the actual code as possible and auto-generating a doc
| site using Doxygen or something similar. Mostly i want this
| because the documentation is closely related to the code. But
| we got stuck because other teams in the company want to use
| Confluence or some other wiki
| RandallBrown wrote:
| I don't know about most, but things like JavaDocs are
| certainly pretty common.
|
| That's not really what we're talking about here though. Like
| you said, it's the concepts and informal stuff that's the
| problem.
|
| I've found autogenerated stuff to only be marginally more
| helpful than just reading the code in the first place.
| InvisibleUp wrote:
| Arguably, if external (not comment-based) documentation is
| important, it would make sense to hire a technical writer whose
| sole job is to ask questions about the codebase and maintain
| proper documentation.
| oftenwrong wrote:
| I find that documentation doesn't help if it isn't conveniently
| where you need it to be. Don't just put everything into the
| company wiki. It might be better to write that information into a
| code comment, a README, or a commit message.
| billconan wrote:
| I think the problem with a graph based model is that
|
| 1. I need an entry point, if things are organized in a graph,
| then I have no idea where to start. Wikipedia has a landing page.
| For causal browsing, when I don't have a specific interested
| topic, I think it's fine. But If I'm new to a code base, I will
| prefer a start point and a step by step way to understand it. In
| that case, I think the graph structure fails to serve that
| purpose. You could create a landing page with a content table,
| but then that would be the same as the tree model.
|
| 2. I won't know the big picture, or the overall scope of a
| document.
|
| For example, when selecting a third party library, I probably
| won't think of any caveats that would affect my use case. If I
| see a caveat section in the content table, I would pay attention
| to it.
| prepend wrote:
| I hate writing documentation, really appreciate reading great
| documentation, and hate reading ok or marginal documentation.
|
| My current approach is just to read source only for docs so
| whatever is in the readme.md and the source files is good enough
| if a project doesn't have someone smart who's into documentation.
|
| And then like "meta docs" generated from markdown in git that
| links to logs of projects.
|
| Most of the stuff I work on is internal only and even paid people
| seem to have bad docs as well.
|
| Source + markdown is good enough and seems to attract more
| internal edits so at least material is more likely to be correct.
|
| Any other scheme seems to fail based on the size of the group so
| I don't bother trying to make a specific structure other than
| "use your judgement, make code readable, make sure any design
| work not in code is in markdown in the same repo."
___________________________________________________________________
(page generated 2021-03-10 23:02 UTC)