[HN Gopher] High-documentation, low-meeting work culture
___________________________________________________________________
High-documentation, low-meeting work culture
Author : seltzerboys
Score : 434 points
Date : 2022-11-22 15:50 UTC (7 hours ago)
(HTM) web link (www.tremendous.com)
(TXT) w3m dump (www.tremendous.com)
| oxff wrote:
| What about the low doc, low meeting culture
| willcipriano wrote:
| I'd like a read the code culture. For me documentation is
| harder to read than code and so inaccurate that you end up
| reading both anyway.
| aliswe wrote:
| it's a good start but it doesn't scale
| twobitshifter wrote:
| What is an example of that working? Just code that speaks for
| itself? How would you ever know why something was done?
| mostlylurks wrote:
| Contrary to popular belief, it is almost always possible to
| express the 'why' (not just the 'what') via code, even if
| comments and/or external documentation are sometimes cleaner,
| simpler alternatives.
| mobjack wrote:
| You ask someone in slack. If that isn't sufficient, set up a
| small 1 on 1 meeting to discuss.
|
| You can't avoid all meetings, but you can keep them few and
| small.
| twobitshifter wrote:
| In long running projects, the people who know the answer
| may no longer be around.
| koonsolo wrote:
| After you are the 3rd person who contacted me for the same
| thing, the next one better read the fking documentation
| that I write.
| Macha wrote:
| Now my ability to find something is limited by someone
| else's availability, and everywhere I've seen this culture
| it's devolved into the same 1-2 people answering all the
| questions as not everyone has a built up map of who knows
| what.
| DenisM wrote:
| Turn around and ask. For small teams it might work well.
| Larger teams require more overhead, hence why hiring more
| people does not produce linear productivity growth.
| cateblanchett wrote:
| i personally can't retain any information in meetings, and i've
| honestly watched meeting recordings back to take notes on
| important info that i totally glazed over at the time. this
| wastes a total ~121 minutes on average, based on their estimate
| of time it takes to refocus after meetings.
| divbzero wrote:
| I like this a lot in principle but would add two notes about
| doing this in practice:
|
| 1. Promote self-documentation as much as possible-- _e.g._
| meeting notes typed straight into Google Doc, discussions typed
| straight into Slack, issues typed straight into GitHub, comments
| typed straight into code--so you're documenting as you go in a
| way that's automatically archived and searchable for future
| reference. There are times when separate out-of-band
| documentation is appropriate, but that takes extra effort and can
| get out-of-date more easily.
|
| 2. Promote an _it's still okay to ask_ culture in parallel with
| the high-documentation culture. Asking questions in Slack can be
| a shortcut to finding the right document or finding out something
| is yet undocumented, and should be encouraged especially if the
| asker has already done a quick search without locating the needed
| information.
| ChrisMarshallNY wrote:
| My personal policy was "No regularly-scheduled meetings" (which
| included things like daily standups).
|
| But I worked for a Japanese corporation, so we had regularly-
| scheduled meetings. I was able to reduce them, though.
| nickdothutton wrote:
| All the corp document stores I've seen, and I think I've probably
| seen most of them by now, would benefit from a full-time
| librarian (or team thereof) and a help-desk to field enquiries.
| Because you have little hope of finding what you want, even if
| you know it's in there somewhere.
| SevenNation wrote:
| I didn't see anything about the hiring process needed to get
| high-documentation culture to work. Many developers don't write
| well. Some don't empathize with the reader and so can't
| communicate complex ideas effectively. Others lack the ability to
| abstract their ideas. Many will be coming from the exact opposite
| of a high-documentation culture and so simply will not value good
| documentation.
|
| Asking people with poor writing skills to work in the way
| described here seems like it could lead to problems without a
| selection process favoring good writers, or at least a training
| system to get new hires up to speed.
| skagenpilot wrote:
| This reminds me of Alan work culture [1], Alan is a startup with
| a zero meeting policy and a very strong culture of writing. They
| check the quality of one's writing during their interview
| process.
|
| Alan leaders also have other strong ethos like "no managers" and
| "complete transparency".
|
| I really wonder if these companies are exceptions or if this
| organisationel model could be replicated more widely. I guess it
| caters to some very specific personality types.
|
| [1] https://blog.alan.com/bien-etre-au-travail/who-we-are-and-
| ho...
| dia80 wrote:
| To me, some of the benefits of having the occasional meeting is
| to create a shared understanding of what's going on and also to
| enable a vigorous group discussion. I'm not sure I would know
| how to replicate that with writing alone.
| tqi wrote:
| Sounds like this works great for them, and an awesome environment
| to be a part of.
|
| However I'd be very curious to see how this evolves as the
| company grows. Personally, I am skeptical that this is
| sustainable in the long term. In my experience, most people are
| a) bad at writing and b) hate reading. And as a company grows,
| and the number of documents that need to be written and read
| explodes, this work pattern eventually becomes untenable. More
| and more meetings get scheduled to cover topics that are not well
| documented, which causes people to have less time/inclination to
| create or consume high quality documents, and it becomes a
| feedback loop.
|
| (Edited to make it clear that I am not against the idea, just
| curious to see how it evolves)
| epolanski wrote:
| > a) bad at writing and b) hate reading
|
| Why does everyone else has to pay the insane price for that?
| cateblanchett wrote:
| doesn't Amazon have a similar structure, tho? i don't know what
| it's actually like to work there (anyone who does feel free to
| chime in) but i've interviewed and from what I can tell they
| put a heavy emphasis on documentation. it's tough to find a
| bigger and more siloed company than Amazon, and it seems to
| work for them.
| fumar wrote:
| Amazon is high documentation, high meetings culture. The
| documentation is reviewed by peers, bar raisers, and leaders
| in a process called document read before being official.
|
| Edit: Someone asked for more detail on high meeting culture.
| There are constant meetings between cross-functional teams,
| various leadership stakeholders, and ongoing operational
| planning. That is not including your day to day meetings
| within your sub team or the follow up meetings from doc reads
| or the new team launch meetings, etc. Amazon tech is a high
| meeting culture.
| cateblanchett wrote:
| so the worst of both worlds
| xenonite wrote:
| Why? I think this sounds great.
| gregoriol wrote:
| If you are writing for reviews, you are not writing for
| your peers. The question is: who will be using the
| documents?
| htrp wrote:
| Read an amazon 6 pager... then try to write one, about
| anything. and then invite all of your co-workers to pick
| apart every single line of your document.
| fumar wrote:
| Correct. Be careful about sharing a document in progress,
| notes, or just simple thoughts in text. People will pick
| it apart word by word. Why? It is the culture Amazon
| created. Sometimes it helps. Sometimes it's a waste of
| everyone's time.
| von_lohengramm wrote:
| Sure, but oftentimes technical documentation is severely
| lacking. PRFAQs, initial design docs, etc. are thoughtfully
| created and thoroughly reviewed, but the actual
| implementation lacks the documentation required to make
| onboarding (be it new team members or new dependent teams)
| as smooth as it could be. My favorite is finding an out of
| date Wiki page from 6 years ago that contains a partial
| list of API method names, descriptions if you're lucky, and
| then nothing else, not even a link to the service's AAA
| page/etc. or a high-level summary of what the service
| _does_ or _why_. With how many moving parts there are and
| how inaccessible non-platform-level documentation is, the
| new hire experience at Amazon can be rather daunting. Even
| SDE1/2s that are a year in often have a very incomplete
| picture of what's going on in their own domain space. Too
| much tribal knowledge.
| FigmentEngine wrote:
| this statement needs some detail, "high meetings" is
| obscuring that meetings use the docs (not meetings with no
| agenda or lots of presentations). meeying use docs as the
| primary driver, be that a narrative or analysis of a
| dataset
| jcparkyn wrote:
| > feel free to chime in
|
| Pun intended?
| erichocean wrote:
| As someone who has to use Amazon's external documentation:
| it's absolutely terrible. Worst docs of any company we have
| to interact with at the API level.
| MikeMaven wrote:
| dehrmann wrote:
| They need high documentation to support their employee churn.
| hinkley wrote:
| People hate reading bad writing.
|
| As someone who dabbled in creative writing before discovering
| my vocation, I see a lot of problems caused by people not
| bothering to explain themselves clearly.
|
| As my time in the industry grew I begin to see people who were
| confused about their own ideas and came to see how many things
| we don't even explain to ourselves. Which likely plays a role
| in how defensive people get about some of their ideas. They
| hadn't considered these things and now they feel out of their
| element.
| jasmer wrote:
| It's shocking how many people don't have the ability to
| organize their thoughts.
|
| I'm ashamed that I was completely guilty of this myself.
|
| At some degree of professional development in software, you
| start to verbalize things, so as to 'explain them to
| yourself' and it helps clear things up.
|
| This helped me understand that 'writing skills' (in this
| context) are frankly more matter of being able to organize
| concepts more than anything else.
|
| A dev who can articulate is literally worth at least 50% more
| than one who cannot.
|
| And to your point, yes, it's funny and scary when someone
| can't describe something they ought to be able to.
|
| If someone can't explain something they are actually a risk
| to the code.
| civilized wrote:
| It's funny how AI and humans struggle with similar issues
| of doing things intuitively and being unable to explain
| themselves.
| dsjoerg wrote:
| Yes! What's threatening about AI isn't that it's smarter
| than humans, but that it's cheaper and more scalable. And
| sometimes smarter. But usually a whole lot dumber.
|
| You reminded me of a fun idea that I'll probably never do
| anything with:
|
| Train an AI which is judged on its ability to quickly
| teach/train _another_ AI how to do the task. So,
| optimizing for ability to explain.
| hinkley wrote:
| Train an AI which is judged on its ability to train
| humans. I don't think we're ever going to really trust AI
| until it can explain itself clearly to humans. And that's
| pretty close to being able to teach.
| vsareto wrote:
| > It's shocking how many people don't have the ability to
| organize their thoughts.
|
| It's organized for them, but not for others. This skill is
| not intuitive to learn, so it shouldn't be shocking.
| hinkley wrote:
| Lately I've been trying to explain to people that the
| Category Error they make is that we have memorized our
| own code, but when we look at the code of others it all
| has to fit into working memory. It's very hard to
| anticipate how other people will see your code.
|
| One of the advantages of mentoring people is that you can
| run User Studies whenever you want. Tell them what the
| code is for and what you want them to do, and then watch
| them try to figure it out themselves, see how far they
| can get before you have to stop the experiment (due to
| them getting frustrated).
| mlazos wrote:
| It works if you hire for people who are good at communicating
| and reward documentation writing in performance reviews
| seltzerboys wrote:
| hiring is probably the main thing. giving some kind of
| documentation exercise to all prospective devs seems to
| alleviate concerns about communication
| tqi wrote:
| Agree that hiring is sure important, but I think as long as
| hiring is competitive, and most candidates are bad at
| writing, then compromises are almost inevitable?
| layer8 wrote:
| If FAANGs started putting more weight on technical-
| writing skills in their hiring, we would get Leetwriting
| and technical-writing bootcamps. Meaning, it's just an
| education issue to some extent, and there's currently too
| little motivation to train writing as a skill.
| whatshisface wrote:
| Leetcode doesn't raise people's IQs, it gives them
| practice effect on tech's favorite IQ test. So I don't
| think leetwriting would work for anything except getting
| practice effect on the new verbal IQ tests.
| closeparen wrote:
| Most people are a) bad at listening and b) hate meetings, but
| that doesn't stop them...
| edgyquant wrote:
| Which is unacceptable for an engineer who must participate in
| architecture meetings.
| [deleted]
| convolvatron wrote:
| does anyone do that anymore?
|
| for me this is the real failure and design documentation
| being shitty is just a symptom
|
| group design is a really important skill, and people don't
| even recognize that its a thing
| origin_path wrote:
| No not to the same extent. Meetings proliferate because
| people love them. LOVE them. Programmers dislike them because
| of flow but everyone else can't get enough of them. I only
| realized after enough years outside the tech industry.
| Meetings are like eating junk food. They make people feel
| important and like they had a busy/productive day, even if
| the actual mental effort required was low and the measurable
| output minimal. Compared to sitting at a desk and focusing on
| a single task, it's far inferior for most people, who find
| that quite exhausting or demotivating.
| tqi wrote:
| I think that's a bit ungenerous to think that programmers
| are somehow different in this regard. Everyone hates
| attending boring meetings. And non-programmers also have
| heads down individual work they need to / would rather be
| doing.
|
| However I agree that the extent of it is the key. I think
| most people actually hate running meetings (it's basically
| public speaking), but they hate writing documents even
| more. It's much easier to "voice over" something than to
| sit and write it out. It's also easier to enforce
| attendance than to police opening and actually reading
| documents. So meetings are the path of least
| resistance/effort.
| origin_path wrote:
| Well people say they hate attending boring meetings, but
| when you observe what people do it's normally the coders
| who actively find ways to skip / who aren't setting up
| new meetings / are requesting fewer meetings. Other job
| roles, at least in my experience, tend to jump to a
| meeting as the first reaction. Developers will say: let's
| discuss it over email. Others say: let's hop on a call /
| grab a room. The number of meetings I've been in where
| there are multiple participants who don't have any
| obvious reason to be there, and who don't say anything
| throughout the entire meeting, is uncountable.
|
| Now you're right it's obviously not that black and white,
| I'm generalizing. But I think devs often under-estimate
| how many people in a typical company perceive meeting
| other internal employees as amongst their primary
| outputs, as an end in and of itself, not just a means.
|
| A good way to observe this in action is to try and
| enforce a rule that meetings must have pre-published
| agendas. Good luck with that! People will just work
| around it or write useless non-agendas because often a
| meeting is not to get something specific done, but is
| used more like a sort of coffee break to split up the day
| and give people something to look forward to between desk
| time.
|
| Something else worth remarking on - a lot of people in
| sales or marketing roles never seem to use word
| processors. They communicate ideas by sending PowerPoint
| decks around, often with a density of words in the slides
| too high to actually project (only readable on hi-dpi
| screens). Where I last worked there were people whose
| working hours boiled down to meetings and PowerPoints.
| They could spend a whole week making a deck, which would
| only be seen by their colleagues in a meeting. I found it
| odd but maybe the slide templates help them structure
| their thoughts.
| booleandilemma wrote:
| This is true. And the more meetings the better, because if
| a meeting starts to get serious, you can just drop for
| another meeting!
| throwawaysleep wrote:
| Also the problem of incentives. I can write well. Why should I
| bother to do so when I am not rewarded for that?
|
| So I just write crap as well.
| Eleison23 wrote:
| My job is sweet.
|
| The management really doesn't go in for meetings, especially not
| all-hands, nor 1:1s for us at the lowest level. We have
| onboardings and special messages and all those are recorded in
| case someone misses, it's no big deal.
|
| Documentation: we have a master SOP document that's about a dozen
| pages, you can read it in an hour and understand it. There's a
| living spreadsheet that's updated so you have to check it on the
| regular. I've also helped build an aid for one particular
| investigative side, but it's optional. There's other
| documentation but it's all ancillary and optional, the biggest
| thing to know is SOP.
|
| There's an #important-links channel on Slack and I do try to look
| through it on the regular, but all you really need to know is a
| small field.
|
| We're all 100% remote, WFH team. We stretch from San Francisco,
| to NYC, to South Africa and coworkers in Australia too.
|
| We're starting to branch out in non-English languages, so I'm
| sharpening my Spanish for the road ahead.
| DustinBrett wrote:
| It would be nice if instead of documentation, we could design
| things to be self evident. Feels like if you need to read the
| docs then the product/service failed to make it clear how to do
| something.
| dsugarman wrote:
| is this the anti-agile manifesto? Personally, I think they got it
| right the first time (https://agilemanifesto.org/), even if most
| modern agile application feels pretty anti-agile today
| [deleted]
| fragmede wrote:
| I was recently introduced to www.Loom.com which is this fremium
| screen recording app and website (no affiliation). Being able to
| have a certain type of meeting asynchronously has been a boon to
| productivity. The async nature of texting is great and adding the
| same thing for audio and video/screen recording has been
| similarly great.
| beckingz wrote:
| Personally, I do not like video recordings. I find them
| inferior to text communications in terms of maximum bandwidth
| and bandwidth to cost ratio (time to write and read).
|
| However, some people are much better at communicating or
| understanding material if its shown visually, which can be much
| more time efficient for both parties sometimes. Every format
| has a place.
| drstewart wrote:
| Video recordings shouldn't necessarily replace written
| messages, they should replace video meetings.
| jl6 wrote:
| High-Documentation is so out of fashion, for all the wrong
| reasons. If you are designing anything that is intended to last
| longer than 6 months, documentation is a critical part of the
| system.
|
| Meetings are great for communicating with people here and now,
| but only writing can communicate with people from the future.
| When you meet with your current colleagues, spare a thought for
| your future colleagues who haven't yet joined, and do them a
| favor by writing things down.
|
| Ability to use written communication is a major differentiator
| between junior and senior engineer.
| icedchai wrote:
| Writing is definitely a critical skill for software
| development. At my last "staff+" job, I spent most of the time
| writing documents that seemingly nobody ever actually read. I
| also reviewed a bunch of them.
| justin_oaks wrote:
| This reminds me of when leadership announces a policy over
| email. Sure, all the people who got the email can follow it,
| but what about people who join the team in the future? Either
| they find out about the policy when they violate it and get
| reprimanded, or they hear about it via word of mouth.
|
| I've seen it a number of times in my career.
| AlexTWithBeard wrote:
| Most of documentation I've seen is either not yet finalized or
| already outdated. Often both at the same time.
| dottedmag wrote:
| Is there a way to stop scrolling hijacking on the sites like this
| one?
| informalo wrote:
| With uBlock *SmoothScroll*$script
| Sohcahtoa82 wrote:
| Honestly, if it wasn't for the fact that setting up a build
| environment in Windows is a god awful experience (As opposed to
| *nix where I can just "apt install <whatever>lib-dev", I'd fork
| Firefox and make a build that strips out access to scrolling in
| JavaScript.
|
| Dear Web Devs
|
| Every web browser already does smooth scrolling out of the box.
| Your JavaScript implementations of it rarely work and only
| create frustration to users. Even they they DO work, it creates
| an unexpected behavior, which is frustrating.
| cosmotic wrote:
| adblock all the scripts =/
| nisegami wrote:
| In order for this to work, you also need a high-reading work
| culture, which is distinct from a high-writing (documentation)
| work culture.
| seltzerboys wrote:
| well if people choose not to read or engage with documentation,
| they're only hurting themselves. in theory, their work
| performance will suffer when compared w/ others. and if it
| doesn't, then they for some reason just don't need to engage
| with existing documentation, so high-reading wouldn't really
| matter. the consequences of not reading documentation will
| either become clear or it won't
| xapata wrote:
| Poor work performance hurts everyone.
| origin_path wrote:
| I tried to create this type of culture at my last gig, where I
| had the unusual privilege of being able to hire almost the entire
| engineering team, alongside my manager who was also very document
| oriented. Unfortunately, it didn't work out. Maybe Tremendous has
| done tremendously better, it's certainly possible, but here is a
| list of things that went wrong, maybe it's useful.
|
| 1. Standard interviews don't assess reading/typing speeds. If you
| want a high documentation culture this is critical. It took way
| too long for us to figure this out but many people in the company
| were significantly slower at reading/typing than us; they found
| long documents overwhelming and would find excuses to not read
| them. Slack conversations became a massive sore spot because
| unknown to us some people felt like they couldn't keep up. They'd
| try to type a question or response and we'd already posted
| another two paragraphs before they got a chance to finish their
| thought. They'd complain to each other that if they asked us a
| question they got back an essay in response, etc.
|
| 2. Documentation requires ownership, otherwise it rapidly becomes
| useless. Standard corp tooling like wikis doesn't make such
| workflows easy. They are however optimal from a corp politics
| perspective (dispersal of responsibility). Maintaining markdown
| based websites works well as long as you have empowered
| maintainers who view document quality as a core job function, but
| you have to force people to submit changes by e.g. rejecting at
| code review time changes that don't update the docs. People will
| moan. They will ask you to do it for them. They will submit
| absolutely min-viable docs changes, they will demand you hire
| technical writers even if they're easily capable of doing it
| themselves. And of course the moment you're not using a git-style
| workflow, just forget it, you have no chance of preserving
| coherency in any sort of knowledge base.
|
| 3. Lots of people aren't just slow but actively HATE reading and
| writing. They will make things up on the spot, or lie, or just
| flat out refuse to do the work rather than sit down and read a
| long document. Jeff Bezos has said about why Amazon uses meeting
| time to force people to read the memo:
|
| _" If we don't, the executives, like high school kids, will try
| to bluff their way through a meeting"_
|
| You _will_ have to fire people for refusing to read things if you
| 're serious about creating and maintaining such a docs-oriented
| culture, which in practice is so unpleasant nobody ever does it
| and so maintaining such a culture is nearly impossible. You will
| also have to flat-out refuse to meet people in order to force
| them to read, because otherwise they'll receive a document and
| just ignore it. I had several cases where one of my most senior
| engineers would assert that a product we used didn't have feature
| X, and I had to correct him by pointing out that the user manual
| discussed feature X in detail. I knew this because I'd actually
| read the user manual cover to cover. Basically nobody does this
| and guess what, if you're the one person on the team who reads
| stuff then you're going to come across as the awkward smart alec
| who makes people look stupid. Sometimes, ignorance is bliss.
| RajT88 wrote:
| This is brutal, but sheds light on why my own documentation-
| heavy style doesn't catch on.
|
| I get questions from people, which can be answered by searching
| my wiki and just finding the right page. I can see the number
| of pages visits with the wiki tool I use, so I am led to
| believe that I'd get a ton more questions if not for my wiki.
|
| So what's the problem? I am just one person in my group.
| There's a couple hundred of us, and I don't think the next most
| documentation-heavy engineer is producing half of what I am.
| (Probably more like a quarter)
|
| Which is a real shame. Part of why I produce so much
| documentation is that I've created by own tooling and processes
| which let me generate vast amounts of useful content on the
| fly, and quickly. I've got 100+ hours of dev work into one
| tool, and I'm pretty sure I'm the only user of that tool
| (although I give presentations on it from time to time). Think:
| A tool which looks up details about an environment, and then
| aggregates those details in markdown format (including links to
| dig in further). Copy > Paste > Save page > Done.
| rcarr wrote:
| I'm convinced that documentation, even for large companies,
| should just be an Obsidian vault of markdown files maintained via
| git which is just rendered on the web either using a simple
| static site generator or using Obsidian Publish. When I brought
| this up at my last company it got dismissed as being 'too
| technical'.
|
| I know git can be tricky but it cannot be that difficult to teach
| people from non technical departments add, commit and push and
| then show maybe one person from each department how to solve
| conflicts. Alternatively, build non technical people a web
| interface for editing and committing but allow the devs to just
| use git as standard. Or there's Obsidian's built in sync but I
| don't know enough about it to know if it scales well in large
| organisations.
|
| What absolutely is definitely not the solution is Confluence. I
| have not met anyone who has a positive thing to say about it. The
| only reason it is being so widely used is because it satisfies
| whoever is in charge of the finances because it comes bundled
| with Bitbucket and Jira.
| j7ake wrote:
| I find Dropbox to have much less friction (almost zero)
| compared to git. In the teams with nontechnical people it is
| often enough to just use Dropbox. Git requires manually
| committing, which is friction and people often forget to commit
| changes.
|
| The fact you need one person technical enough to resolve
| conflicts is already a deal breaker.
| PartiallyTyped wrote:
| Setup a service with Dropbox sdk and python to pull the data,
| commit them, and push (even forced) to git.
|
| At least you will have multiple revisions.
| jbverschoor wrote:
| Well, you can actually just script that. Dropbox is fun,
| until you want previous versions.
|
| At the place I worked for 22 years ago, we had an SMB
| fileshare for designers/front-end devs (html templates +
| templating lang), which would simply commit everything to CVS
| at night.
| mayas_ wrote:
| I'm a CTO in a startup and all our docs are in .md files,
| mermaid diagrams with dynamic Table of Content generation.
|
| We have two repos: Product (to anything relating to product)
| and Wiki (anything else, ranging from onboarding checklists,
| brief design documentation of key parts of the code ... to meta
| documentation)
|
| Although our team is small by many standards (8) everyone likes
| it.
|
| We spend a ridiculously small amount of time on meetings.
|
| The obvious and great upside is the code/documentation
| integration which has virtually 0 context loss.
|
| One downside however is indeed the difficulty of git branching
| to non-developers.
|
| Once in while I find myself debugging a messed up version.
|
| But I'm willing to pay that price.
| vsareto wrote:
| >I know git can be tricky but it cannot be that difficult to
| teach people from non technical departments add, commit and
| push and then show maybe one person from each department how to
| solve conflicts
|
| Nah, that's going to be a crapshoot. You want a few people who
| know git and do this for a full time job and that's all they do
| - manage the documentation git repo.
| tryauuum wrote:
| confluence is ok, though I think I had problems with literal
| search: https://jira.atlassian.com/browse/CONFCLOUD-69222
|
| What's the benefit of your solution? I mean git has excellent
| history lookup capabilities, but that's the only benefit I see.
| Maybe another one is that you can update documents without
| leaving cli..
| rcarr wrote:
| For starters, the Confluence editor is absolutely dire. We
| can all stand here and sing til the cows come home about how
| it shouldn't be the world we live in, but the reality is that
| not a lot of people want to or have the time to write
| documentation so we should be making it as easy and fast as
| possible to do. As much friction as possible should be
| removed. It does not get a hell of a lot easier or quicker
| than writing a Markdown file.
|
| Second, because it is plain text, search is blisteringly fast
| using any number of different tools. Following on from that
| for a third benefit: portability. You're not tied to any one
| service. You can use any text editor for editing and you can
| use a multitude of different solutions for publishing.
| Version control? Use whatever you what.
|
| Another benefit: easy linking of files using [[wikilinks]]
| and block inclusion. If this is done properly, you can also
| use the graph view to get an oversight on how your code
| affects other parts of the codebase at a glance.
| csharpminor wrote:
| I don't like Confluence either, but the platform is only 10% of
| the problem. Knowledge Management platforms are something that
| PMs love to debate, purchase, and use to get promotions. So you
| end up with a company that has 6+ platforms. This is way worse
| than having one unified, crappy-UX, wiki.
|
| Finding the perfect documentation platform becomes a waiting-
| for-superman game. Everyone loves to complain, but nobody wants
| to put in the actual work to write clear content, define
| information structure, consider audience, etc.
|
| The real solution is hiring people who are excellent writers.
| To do this, leadership must be good at reading and writing
| themselves (not a given) and be able to recognize top
| contributors.
| howenterprisey wrote:
| I use Confluence pretty heavily at work (I write most of our
| docs) and I like it. Any annoying UI elements, I hide with
| ublock origin. I don't mind the lag, although I do wish it were
| faster.
| tomxor wrote:
| > I'm convinced that documentation, even for large companies,
| should just be an Obsidian vault of markdown files maintained
| via git
|
| I had the same concern, internal documentation should be in a
| portable format... and I managed to mostly successfully get us
| to change to MD text files in a git repo.
|
| I, and others, were tired of it being locked up in proprietary
| platforms like google docs - which ironically has terrible
| search capability and is horribly slow. Some of the devs
| already wrote documentation in markdown and plain text along
| side code (Also I hear talking about yourself in the 3rd person
| is the first sign of madness). So a git backed wiki in text
| files was what I wanted. But it also needed to generate commits
| from the front end for the less technical, and preferably
| needed oauth to delegate access control to some other system.
|
| "Golumn" filled this space first I believe, but doesn't (or
| didn't at the time) have the commit or oauth capability. So I
| settled on a fork "Jingo" which does. I'm not completely wedded
| to Jingo, which is a nodejs app, I haven't dug too deeply into
| it and so my confidence in it is unknown... but this is
| effectively data driven design, md text files in git... the
| code (which is not part of the same repo) is disposable.
|
| I set this up 3 years ago and haven't touched it at all. This
| has been mostly successful gaining more traction over time.
| People who have no clue how to use git are generating gits
| commits on a daily basis through the front end - others are
| using the repo directly. Google docs still has it's place for
| arbitrary word type stuff, but most internal internal reference
| type material now gets put into the wiki as a preference, since
| it's way more searchable, and orders of magnitude faster to
| access.
|
| [edit]
|
| To be clear, i'm in a small company where it's easier to change
| or try things like this.
|
| I also got the same expected pushback, concern over MD being
| too limited compared to google docs and the solution being too
| technical. but if you can just convince people to trial it for
| long enough with an exit plan, they will usually obtain a more
| balanced view weighing the tangible benefits more highly and
| weighing the negatives or concerns less after actually
| experiencing it... in this case most people realise that all
| the bells and whistles of google docs are not critical, and the
| benefits of the searchability, speed and portability are huge.
| rcarr wrote:
| Hadn't heard of this before, looks very cool. For anyone
| interested: https://github.com/claudioc/jingo
| throwawaaarrgh wrote:
| Does using Git contribute _anything_ of value to the
| documentation that you could not possibly get _without_ git?
|
| The answer is, of course: no. You just want it because it's
| familiar to you. Which is fine... if you were the only person
| using it.
|
| Confluence is actually the best solution, hands down. It has a
| WYSIWYG. It supports Markdown. It has an API. It versions all
| content. It has fine-grained access control. It does not
| require granting a user access to a repo to write to a file. It
| has much more rich content to better convey information clearly
| to humans. It has full text search. Page management is simple
| (rename a page and it auto-redirects). And no other solution
| does all of this as easily or effectively.
|
| The people who complain about Confluence simply don't care
| about use cases outside their own, and haven't taken the time
| to learn it. I am 100x more productive with Confluence than you
| are with Git and Markdown. And real people will actually be
| able to use what I've made there without learning complex tools
| or jumping through hoops.
| grok22 wrote:
| You talking about 'wiki'?
| antupis wrote:
| This might be stupid question but why nobody has not built this
| kind git-based system to nontechnical people.
| pxc wrote:
| There's Gollum, which powers the built-in wikis on GitLab and
| GitHub. Its web UI handles making commits for you.
| Terretta wrote:
| https://www.craft.do
| lastofus wrote:
| Some people have built it. For example:
| https://www.macupdate.com/app/mac/49459/draft-control
| kccqzy wrote:
| You cannot expect non-technical people to use git from the
| command line. I still like your idea though: the documentation
| can be based on markdown files in a git repository, but then
| you have to build or find a web-based WYSIWYG editor with Git
| support for non-technical folks. If you use GitHub already, it
| wouldn't actually be so bad to teach the non-technical folks to
| use the Git UI only to make documentation changes.
| rco8786 wrote:
| Saddling entire companies with having to learn git, even at a
| basic level, is a hilarious idea.
| ravenstine wrote:
| I wouldn't even bother with the static site generator. While I
| like the idea of STGs, in my opinion, they all suck. And now
| there has to be someone to maintain how those pages are
| rendered and know how whatever thing like Jekyll works.
|
| Just let developers either read the markdown files as-is or set
| their IDE to render markdown previews by default. I prefer the
| latter because I don't have to wait for someone who's on
| vacation half the time to render the latest docs.
|
| When it comes to API documentation, everything should just be
| inline comments in the doc format of choice for the team. Don't
| bother rendering this out, because every flipping tool ever
| invented for converting inline documentation into HTML fails on
| something simple. Developers can read the inline docs as-is
| and/or rely on their IDE to provide them hints from those docs.
|
| If you have to deploy your documentation, that's how you know
| you might as well give up. It's one thing to deploy
| documentation for 3rd parties, but for documentation being used
| internally there's few good reasons to turn the documentation
| into its own website. That's extra work that I've never seen
| increase productivity or developer happiness. Don't put
| documentation behind one or two guys with special permissions
| to press a deploy button. If you do, the documentation will
| _always_ be out of date as soon as it 's rendered.
|
| Remove as many reasons that devs won't write documentation as
| you possibly can.
| rcarr wrote:
| I do think just using the folder of markdown folders is far
| preferable to browsing on the web wherever possible but
| there's definite use cases where it's unavoidable. I do think
| this is a very strong case for using Obsidian however,
| because you literally don't have to mess about with
| maintaining any kind of SSG, you just put `publish: true` in
| the metadata of whatever note you want publishing and then
| just click the Publish button and it's there on the website.
| vlmutolo wrote:
| Rust's rustdoc tool does an excellent job converting comments
| to HTML.
|
| The documentation for almost every public Rust library is
| automatically rendered and hosted on docs.rs and it's
| incredible to have that consistency.
|
| Just check out this Regex type and the awesome documentation
| for every method, all taken from inline comments:
|
| https://docs.rs/regex/latest/regex/struct.Regex.html
| loudmax wrote:
| This is what the Gitlab wiki does. There's a markdown+git
| interface for technical folks and a web interface for normal
| people.
| kfrzcode wrote:
| I like Confluence! It serves it purposes and provides a lot of
| niceties, and is - as you mention - integrated with other
| Atlassian tooling. Nice ecosystem!
| amendegree wrote:
| You'd have a much easier time getting this adopted if you
| created a fancy GUI on top of the infra you just detailed out.
| Most people don't want to deal with git, no one wants to write
| in markdown all day, and the more obstacles you introduce to
| making documentation the less documentation gets made.
|
| If the two options are confluence and sharepoint I choose
| confluence every time. Somehow people have decided that because
| sharepoint can do document store and html it's a kb. and
| because it comes with O365 exec's love it because its "free".
| [deleted]
| PragmaticPulp wrote:
| > I know git can be tricky but it cannot be that difficult to
| teach people from non technical departments
|
| This is far more difficult than you're suggesting. Git still
| confuses a lot of junior and mid level devs the second anything
| deviates from their memorized command workflow.
|
| If you're expecting non-technical people to have to learn git
| just to edit the documentation, they're just not going to use
| it at all.
|
| Writing and aggregating good documentation needs to be easy and
| simple. Gating documentation behind git is the opposite of that
| for non technical people.
| divbzero wrote:
| GitHub wikis or something similar can work well as an in-
| between option: edit in browser or _git clone_ , whichever is
| easier in your context.
|
| https://github.blog/2011-01-17-git-powered-wikis-improved/
| jorgesborges wrote:
| In fact you lost non-technical people at Markdown.
| pxc wrote:
| Non-technical people used to learn bits of HTML just to get
| sparkly backgrounds on their MySpace pages. Markdown is
| absolutely masterable by anyone.
| RadiozRadioz wrote:
| > Non-technical people used to learn bits of HTML just to
| get sparkly backgrounds on their MySpace pages.
|
| I'm going to take a slightly different interpretation of
| your comment because I think it's an interesting
| discussion: are the non-technical people of today less
| technical than the non-technical people of the MySpace
| days?
|
| From what I have observed, I would say yes. If you took
| the bottom 10% of users back then, you might have a hope
| of teaching them HTML. Today? No chance. In particular I
| think "willingness to learn anything" has really waned.
| yamtaddle wrote:
| There were _tons_ of users in the 90s who didn 't have a
| clue how to use a computer--I mean even at a very
| rudimentary level--and just followed memorized or
| written-down steps, getting lost almost immediately if
| anything went wrong. Luckily for them, software was way
| less likely to throw up "what's new" modals seemingly at
| random, interrupting whatever they were trying to do,
| back then :-/ (edit: or to "improve" [pointlessly re-
| arrange] their UI while the user was away from the
| computer, for that matter)
|
| If there are more of them now it's probably because
| computer use expanded 100 fold since then, at least, and
| the largely self-selected 90s users of the Web,
| especially, tended to have greater-than-average interest
| in learning computer crap, so a high proportion of new
| users were the can't-or-don't-want-to-learn sort. In the
| 90s a computer still _might_ not be the centerpiece of an
| office worker or middle manager 's desk, and most folks
| used computers very little at home, if they even had one
| (data I'm seeing indicates % of households in the US with
| a computer only hit 50% in 2000).
| jorgesborges wrote:
| Definitely. My thought is rather that it's an additional
| point of friction that makes selling a workflow like this
| more difficult.
| nonethewiser wrote:
| > This is far more difficult than you're suggesting. Git
| still confuses a lot of junior and mid level devs the second
| anything deviates from their memorized command workflow
|
| Try explaining that they can't push to the repo because they
| cloned the http URI and need to generate an RSA token and use
| SSH instead. Better yet, try to figure out that's the problem
| when they give you a totally unhelpful version of what the
| problem is.
| carom wrote:
| Or just download Github Desktop onto their machine and show
| them how to use it.
| rcarr wrote:
| I do get what you're saying because I struggled with it for
| ages. There are good GUI tools like Sublime Merge for easy
| conflict resolution now which would be one solution. I do
| think a web interface that just automatically commits by just
| adding your text in addition to the new text along with a
| warning would probably be the easiest solution and then just
| have someone edit it after the fact. It's not been my
| experience that there's a hell of a lot of merge conflicts
| going on with documentation anyway but I could see how it
| could happen if you had multiple non technical people
| actively working on a project.
|
| Another not great but possible solution could be for non
| technical people to work on something like a Google Doc when
| stuff is in highly active development and to then copy this
| to a markdown document later when its solidified.
|
| I do think that as a society we have to start looking at
| stuff like this as a new essential skill though. We wouldn't
| expect people to be working without basic literacy, numeracy
| and computer skills and I think we are going to have to start
| looking at upgrading our sense of what basic computer skills
| entails to include stuff like git and teaching it in schools
| from an early age.
| remus wrote:
| I think even the idea of merging changes is a step too far
| for all but the most technical users. Most user's idea of
| what it should look like start and end at a word-like UI,
| so having to introduce the idea of merging different copies
| together and resolving conflicts is too far outside that
| view. In my opinion this is why Google docs has become
| popular because it solves that tricky problem of having to
| think about how your edits interact with someone else's.
| rcarr wrote:
| I do agree that an online google doc style WYSIWYG
| markdown solution would be preferable for non technical
| and then git and markdown for technical would be the
| ideal solution.
| evolve2k wrote:
| My sense is the markdown/git/render a documentation wiki
| with mkdocs is mostly solved. The issue is having that
| easy interface for non-tech folk.
|
| And related to this is the state of WYSIWYG markdown
| editing.
|
| The Basecamp folks created the very polished Trix rich-
| text drop-in which is a replacement for TinyMce, which
| while the standard seems to carry issues.
|
| Basecamp explained the issue with most approaches as
| such:
|
| > Most WYSIWYG editors are wrappers around HTML's
| contenteditable and execCommand APIs, designed by
| Microsoft to support live editing of web pages in
| Internet Explorer 5.5, and eventually reverse-engineered
| and copied by other browsers.
|
| > Because these APIs were never fully specified or
| documented, and because WYSIWYG HTML editors are enormous
| in scope, each browser's implementation has its own set
| of bugs and quirks, and JavaScript developers are left to
| resolve the inconsistencies.
|
| > Trix sidesteps these inconsistencies by treating
| contenteditable as an I/O device: when input makes its
| way to the editor, Trix converts that input into an
| editing operation on its internal document model, then
| re-renders that document back into the editor. This gives
| Trix complete control over what happens after every
| keystroke, and avoids the need to use execCommand at all.
|
| Unfortunately Trix does not render markdown so can't be
| used in a markdown documentation workflow.
|
| Has anyone seen a decent implementation of WYSIWYG for
| markdown that has the necessary polish to be non-tech
| friendly?
| andfrob wrote:
| This would be worth checking out, which shows how
| CKEditor implements markdown editing:
| https://onlinemarkdowneditor.dev/
| rcarr wrote:
| I believe Obsidian are using ProseMirror or CodeMirror,
| the logo is at the bottom of CodeMirror so I assume it is
| the latter. There was this forum post from one of the
| Obsidian team a few years back asking about it
|
| https://discuss.codemirror.net/t/implementing-wysiwyg-
| markdo...
|
| https://codemirror.net
|
| https://prosemirror.net
| jonwest wrote:
| GitHub does offer the ability to modify files within the
| web UI and open a PR from there.
| stcredzero wrote:
| _> This is far more difficult than you 're suggesting. Git
| still confuses a lot of junior and mid level devs the second
| anything deviates from their memorized command workflow_
|
| Given the number of non-programmers who _Really Need_ the
| functionality of git, who probably won 't be able to hack
| dealing with it, doesn't this indicate that there's some huge
| vein of untapped value to be won by whomever cracks the
| problem? (Version control for business people?)
| joegahona wrote:
| > Writing and aggregating good documentation needs to be easy
| and simple. Gating documentation behind git is the opposite
| of that for non technical people.
|
| How do you find a happy medium between this and a Confluence-
| like free-for-all, where anyone can create/edit a page?
| WorldMaker wrote:
| There are Wiki-like interfaces for git+Markdown: GitHub's
| wikis, gitit, and more.
| vasco wrote:
| Most of the issues with Confluence I've seen are lack of
| organisation, out of date information mixed with up to date
| pages and really poor search / discoverability. The fact
| that people can just edit or create a page at any point is
| one of the better parts because it's easy for someone to
| fix something up during onboarding, during a drive-by
| consultation etc.
| otikik wrote:
| Google Docs
| user3939382 wrote:
| The Google Docs/Sheets version history strikes a pretty good
| balance of friendliness and power. The biggest weakness I've
| seen with it in the hands of non-technical users is that they
| don't know it's there.
| waboremo wrote:
| An easier one stop shop alternative is just Notion. Recommend
| it for the reason of having an internal wiki/documentation.
| Probably one of the only real use cases for Notion, everything
| else (like personal note taking or time organization) is
| horrible on it.
| rcarr wrote:
| This was actually my next suggestion when Obsidian got shot
| down. It's definitely a nice half way house between the two.
| Again it got dismissed albeit this time with no explanation,
| I assume because the request for feedback and suggestions
| wasn't actually anything of the sort but basically a pretend
| exercise on behalf of management to 'show we're listening'.
| [deleted]
| icelancer wrote:
| That just sounds like rebuilding Notion internally, and this is
| coming from someone who uses Obsidian locally and Notion
| company-wide.
| tryauuum wrote:
| notion lost appeal when I noticed that search doesn't work.
| E.g. I have a page with wireguard mentioned in text and I
| cannot find it when searching for wireguard.
| [deleted]
| koonsolo wrote:
| That is indeed too technical. Try to explain how inserting an
| image is not just copy paste.
| rcarr wrote:
| 1. Paste image into assets folder.
|
| 2. Write .
|
| It's not that hard really is it.
| vasco wrote:
| Have you worked with non-technical teams, ever? Perhaps in
| teams of very young and gamer-type people this would work,
| but in any real world team I've been in, this would not in
| fact be easy unless there's a real time preview and a
| button you can click that auto-generates that snippet.
| People would forget the exclamation mark, mixup the
| brackets with the parenthesis, not know how to reference
| the right path to the image, and ask a developer to help
| them out.
| someguydave wrote:
| If someone is confused by markdown syntax it is hard to
| imagine how they contribute professionally.
| mym1990 wrote:
| Maybe you should try to imagine a little harder. "If You
| Judge a Fish by Its Ability to Climb a Tree, It Will Live
| Its Whole Life Believing that It is Stupid"...or in this
| case you will live your whole life believing every non-
| technical person around you is stupid...which just sounds
| miserable for everyone involved.
| rcarr wrote:
| Well presumably this would be less of an issue if you had
| easy to use, easy to search and easy to maintain
| documentation, you know, maybe in the form of markdown
| files with a search bar where you could type 'how to
| paste image into documentation' in case you forgot...
|
| At the end of the day, if you've got someone who can't
| work out how to drag a file into a folder and then type
|  after you've shown them a
| couple of times, is this really the person you want
| writing the documentation for your process?
| goatlover wrote:
| So you're replaced something that's simple as paste in
| office documents with two separate steps, one outside the
| app requiring the user to navigate to the assets folder,
| and the second requiring remembering specific syntax.
| eastbound wrote:
| "Stop, you were born with computers so you don't notice
| it, but I'm not technical enough to paste an image in a
| Word document."
|
| -- The intern I just had to fire last month. She
| pretended because her generation was born with iPhones,
| that knowing advanced computer skills like Cmd+V was
| something that wasn't a given at 21 years old. It blew my
| expectations about school - but at least school teaches
| them to find unexpected arguments.
| georgebarnett wrote:
| She grew up with computing systems that had no concept of
| keyboard shortcuts and intentionally abstracted away the
| concept of the file system and documents.
|
| I think her assessment of the situation is fair.
| rcarr wrote:
| Exactly, there is a certain level of basic technical
| competence you have to have to work any position, not
| just computer based ones. No-one is suggesting you have
| to do it all alone but if you're not willing to put the
| effort in and learn, or able to carry out a task after
| repeatedly being shown how then you're the wrong person
| for that job.
| rcarr wrote:
| Not really because if you're using Obsidian you can just
| copy paste images and it will handle the syntax and
| moving the asset into the correct location anyway. But is
| taking an hour to read through a markdown cheatsheet
| really the worst thing in the world if what you end up
| with is far more useful and maintainable documentation?
| Seems like a pretty big pay off for not a lot of staff
| training.
| phailhaus wrote:
| > But is taking an hour to read through a markdown
| cheatsheet really the worst thing in the world if what
| you end up with is far more useful and maintainable
| documentation?
|
| This makes no sense given that you get the same payoff by
| using something like Atlassian's wiki. No git, no
| markdown, none of this nonsense, users can just
| immediately hit the ground running with advanced
| formatting support and version history.
|
| I think you're lacking a lot of empathy for nontechnical
| users. I don't see how you could ever argue that your git
| + Obsidian stack is "more valuable" than an off-the-shelf
| wiki solution.
| rcarr wrote:
| Because I'm tied into Atlassian's ridiculous way of doing
| things as opposed to a completely open file format I can
| take anywhere and edit in any number of editors.
|
| I have empathy for non technical people in that I believe
| Markdown is far easier to use than Atlassian's interface.
| Every single developer I've worked with has been tearing
| their hair out when trying to write documentation on
| Confluence and documentation never got written as a
| result. If this is the experience for technical people,
| what on earth is the experience like for non-technical
| people?
| phailhaus wrote:
| > Because I'm tied into Atlassian's ridiculous way of
| doing things as opposed to a completely open file format
| I can take anywhere and edit in any number of editors.
|
| Nobody cares. Really, they do not. This doesn't help the
| business, it adds way too much overhead, and requires
| nontechnical people to understand _markdown and git_.
|
| I have never heard nontechnical people complain about the
| Confluence wiki. From their perspective, everything Just
| Works. Imagine having to tell them all the things that
| they can't do because of Markdown's limitations, and how
| much harder it is to do drop-dead simple things like
| adding tables. Can't you see how that's a 100x higher
| barrier than _anything_ you can complain about for
| Atlassian? Anything that you 're frustrated at with their
| editor, you probably can't even do in Markdown. All the
| markdown stuff is easy.
| rcarr wrote:
| > Nobody cares. Really, they do not. This doesn't help
| the business, it adds way too much overhead, and requires
| nontechnical people to understand markdown and git.
|
| They absolutely care if one day Atlassian decides to hike
| prices to levels they deem unreasonable and now their
| entire documentation is locked in a proprietary format or
| if Atlassian go under, are purchased by a competitor etc.
|
| > I have never heard nontechnical people complain about
| the Confluence wiki. From their perspective, everything
| Just Works.
|
| This has not been my experience at all. I've had tons of
| business analysts join in the Confluence moaning during
| meetings, both for editing and trying to find stuff.
| 'Just works' is not how I or anyone I worked with would
| describe it.
|
| >all the things that they can't do because of Markdown's
| limitations
|
| what are these things you're so desperate to do in Code
| Documentation that you can't do in markdown?
|
| > how much harder it is to do drop-dead simple things
| like adding tables.
|
| This has been a solved problem for a while now. One of
| the very first Obsidian plugins was the advanced tables
| plugin which makes it super easy to make and edit tables.
| There's also other apps like Table Flip. I'm sure there's
| probably plugins for other editors like VS Code or Table
| functionality built in to other markdown editors.
|
| The only reasonable point you've got is about git. Like I
| said in the original post, a WYSIWYG web interface for
| non-technical folks which just auto commits would be
| preferable whilst still allowing regular git and markdown
| for technical folks. There's also nothing stopping anyone
| from doing an intermediate page if conflicts are detected
| with a three way conflict resolution page a la Jetbrains
| Editors with a magic wand auto solve. Maybe the WYSIWYG
| editor could automatically update if changes are detected
| a la Google Docs. There are lots of potential ways of
| solving the 'git hard' issue. There is also the built in
| Obsidian Sync and Publish which use git behind the scenes
| and give you access to full version history although I
| don't know if they scale well or not.
|
| At the end of day, conflicts in documentation are less of
| an issue when they do happen because they're not going to
| cause an entire crash of a program, you're just going to
| have some text that doesn't make sense. In the very worse
| case scenario non technical people could just copy and
| paste things back into place from git history. Other than
| time wasted, it's not the same disaster as if a code
| conflict is not resolved properly.
| pxc wrote:
| > This makes no sense given that you get the same payoff
| by using something like Atlassian's wiki. No git, no
| markdown, none of this nonsense, users can just
| immediately hit the ground running with advanced
| formatting support and version history.
|
| Except that like all WYSIWYG editors, Confluence's editor
| is buggy and unpredictable. You can _only_ use it in a
| browser. Because it doesn 't even have a 'raw' editing
| mode anymore, you can't work around the WYSIWYG editor
| when it's broken. Uploading or converting to it from
| external sources is a PITA, when it's even possible.
|
| If you want technical documentation that developers are
| going to maintain, it has to be a joy to work with _in
| their own editors_.
|
| WYSIWYG isn't actually better. It's a broken paradigm,
| and that's why every single attempt to move Wikipedia
| over to a WYSIWYG editor has failed.
| tgsovlerkhgsel wrote:
| Make it copy-paste. Automatically upload it to the image blob
| storage and insert the image code, then show the WYSIWYG
| preview.
| Terretta wrote:
| > _I 'm convinced that documentation, even for large companies,
| should just be an Obsidian vault of markdown files maintained
| via git which is just rendered on the web either using a simple
| static site generator or using Obsidian Publish_
|
| This, except for normals, sort of exists:
|
| Craft: https://www.craft.do/solutions/businesses
|
| Default is internal only, but you can allow sharing, which
| creates a web URL that can be privately or publicly shared (and
| can be on your own custom domain).
|
| It has versioning, it has comments, it has real time multi-
| editor collaboration. An entire conference room, in person and
| virtual, can co-edit in true real time without anything blowing
| up, a feat not to be tried in Word, or even Google Docs.
|
| Most firms should stop looking and just try Craft. Encourage
| everyone to do everything there, see what happens.
|
| Note bene: it happily imports markdown, also exports Word, PDF,
| Markdown, and Textbundle, and can feed a static site gen.
|
| They also keep busy: https://www.craft.do/whats-new
|
| // I use Obsidian for myself, but Craft to collaborate with
| non-engineers. I've also been known to recommend FOAM to
| engineering teams, coupled with mkdocs and a good theme for
| static site gen, such as material for mkdocs:
|
| https://foambubble.github.io/foam/
|
| https://github.com/squidfunk/mkdocs-material
|
| For eng teams already living in VS Code, it's hard to beat PKM
| where you already are.
| primax wrote:
| This looks great, but no Android or mobile support outside
| iOS is a big negative
| technological wrote:
| Personally I feel documentation wont be such hard thing to do if
| ppl are not very particular about formatting and making it look
| good.
| sneak wrote:
| This doesn't work at most companies because most people don't
| know how to type properly.
|
| Thus they would rather speak at a meeting than type into a form,
| because they can speak several times faster than they can type.
|
| I don't hire people who don't know how to type properly (or won't
| commit to learning).
| krapspark wrote:
| I wanted to read this article but the sluggish scrolling on the
| page made me leave the site. I appreciate the approach in the
| first few paragraphs I read, though. haha
| willchis wrote:
| The motion and blurring made me feel sick so I quit reading
| too!
| blueboo wrote:
| I love the idea, but we should be taking pinches from our fancy
| sea salt. Tremendous has less than a hundred employees. Just
| small enough that people can probably individually track the
| complete state of their respective arm of the business.
|
| Marvelous is also about to face a significant stress test with
| the holiday season, both from retail usage of their product and
| from vacations of their employees. I wonder how routinely highly-
| documented the agendas will be when competitors start sniping
| their biggest clients as their service crashes from overcapacity.
|
| Reversion to the mean is coming -- what would be interesting
| would be to hear successful strategies to resist it.
| incomingpain wrote:
| Sounds like my current job which I love.
|
| My last job, low documentation, low meeting. Basically every bit
| as bad as you might expect. Every job you basically have to
| figure everything out from scratch.
|
| 2 jobs ago, low documentation, high meeting. Daily meetings to
| discuss what I'm working on and how little the rest of the team
| is doing. Yet nothing changes or improves.
| manv1 wrote:
| All developers should spend time working in support. That time
| will make them appreciate the incredible power and utility that
| documentation provides to everyone...including your future self.
| convolvatron wrote:
| I find it to be really interesting for the first day or
| two...then I realize that our customers are often really
| terrible people using our product for really bad reasons and it
| undermines my whole faith in the project
| bluetomcat wrote:
| "High-documentation" isn't the cure, either. Just write quality
| software with well-defined interfaces, minimal dependencies and
| smooth building processes. I want to be able to build the thing
| without frustration, to start playing with it in order to learn
| its internals and debug it. Only then can I be comfortable enough
| to start implementing features and changes.
| rqtwteye wrote:
| It's devastating to learn after more than 20 years in the
| industry that the secret is "Just write quality software with
| well-defined interfaces, minimal dependencies and smooth
| building processes". If I and my colleagues had known only
| sooner about this straightforward and actionable advice...
| DenisM wrote:
| That's how I often use documentation - start documenting
| something, then ask myself "should the code be fixed to avoid
| the need to document this part? Yes, yes it should".
|
| A long provisioning instruction became much shorter as a result
| of automating it by reducing the need to document.
| ip26 wrote:
| Are you pitching less documentation or none? It doesn't seem
| like codebases are better when the architecture is unwritten.
| DenisM wrote:
| As little as feasible, but no less than that.
| samhickmann wrote:
| giogadi wrote:
| "Just write quality software"
|
| That's quite a load-bearing "just" there.
| drewcoo wrote:
| IMO, "quality" is going to be the sticking point.
| ip26 wrote:
| No problem, we just need to hold a few meetings to define
| what counts as "quality", and write it down in some good
| documentation.
| agtorre wrote:
| I've also seen a lot of benefit of grouping recurring meetings
| all in the same time slot daily. I.e. all team rituals from 10-11
| am daily.
| celestialcheese wrote:
| From the outside, Gitlab seems to have solved this with a medium-
| sized org with all remote, and it sounds like a dream remote
| workplace.
|
| Async communication, full transparency, 90-day retention in slack
| which forces decisions into documentation if it's important,
| issues/threads for discussions, and handbook for SOPs [1]
|
| Anyone have experience with this directly that can speak to if
| this works in practice?
|
| Or is Gitlab just really good at marketing their methodology as a
| tool to sell more subscriptions?
|
| 1 - https://about.gitlab.com/company/culture/all-
| remote/handbook...
| peterbozso wrote:
| GitLab employee here. Can confirm, it works exactly as
| advertised to the outside world.
| goldenshale wrote:
| If only we could have an AI do the documentation...
| lifeisstillgood wrote:
| >>> It's not just about the meeting, which is itself a thirty to
| sixty-minute intrusion on someone's day. It's about the time
| wasted anticipating a meeting, where people feel they don't have
| the time to plunge into an important project.
|
| Oh god yes! This - a thousand times this !!
| DubiousPusher wrote:
| I think this approach has many benefits. The main problem with
| most collaborations in which documents are used to replace
| conversation is that without a disciplined framework for
| structuring documents it's very easy to get lost in them.
|
| -documents go out of date, people are usually up to the minute
|
| -documents don't allow you to ask questions people do
|
| -documents never forget, people do (not forgetting seems like a
| good thing but try working through a 5-10 year old team wiki or
| OneNote and you'll see why it can be good)
| jayjay12389 wrote:
| I think there is a trade off on amount of time spent on the high-
| documentation approach and how large you are. Totally makes sense
| for larger organisations but less so for startups. There is
| probably a number of consumers of the information produced at
| which point it makes the most sense to do go for 'high-
| documentation'. I wonder if anyone has done deeper research on
| this.
| _def wrote:
| I'm desperate for less meetings. How do you fight against Scrum?
| It seems like at some companies it's the only way they know how
| to "get things done", even if it doesn't really work
| ifloyd wrote:
| Our work culture's obsession with meetings, which is dwindling,
| it seems, is due in large part to our desire to perform as part
| of 'productivity theater.' this has mostly been driven up by wfh.
| but it's interesting to me that so many people focus on
| performativity vs. output
| uxp100 wrote:
| Is it dwindling? I think the number of hours of meetings I
| attended approximately quadrupled due to WFH. Limited
| conference rooms making > 1 hr meetings impossible was
| wonderful.
|
| Or are you saying it was dwindling, but it surged up due to
| wfh? Then I guess I agree, though I'm not sure if it's due to
| productivity theater, or physical constraints being removed
| thisisbrians wrote:
| I think about this a lot. "Managers" are under pressure to make
| sure their teams are meeting goals/deadlines/whatever, so they
| are anxious, so they make efforts to observe and oversee
| "performance". Seeing people in meetings and diligently
| "working" makes them feel better about their teams'
| performance. But what really matters is outcome...which is very
| difficult to measure for a lot of software teams, and even
| harder for individuals. The irony is that the efforts to
| measure/ensure performance, in many cases, actually impede
| material progress towards the desired outcomes.
| ip26 wrote:
| On the other hand, thirty minutes a week seems like a small
| overhead to pay if you're concerned a team might otherwise
| lose focus & direction entirely. Not, to be clear, that they
| are lazy, but instead that they could be diligently
| working... on the wrong thing.
|
| I can understand it both ways.
| thisisbrians wrote:
| It's certainly a spectrum. 1<>1s and vision alignment
| meetings are super important. Standups too, if that's your
| thing (I like them, but they must be run well). A lot of
| other stuff can start to get noisy in my opinion.
| hackeredje wrote:
| Documentation should be atomic, not large pieces of text. And
| each atomic item has bidirectional dependencies to other atomic
| pieces or methods or classes or requirements or terms etc.
| synu wrote:
| At my company we make all meetings optional, this really helps
| create the right incentives both for hosts and attendees. As a
| result we have very few meetings, but the ones we have work well.
| https://www.synura.com/handbook/general/meetings/#all-non-11...
| throwawaaarrgh wrote:
| 1. If you want this culture, make it a rule, the way GitLab did
| with their Handbook-first Culture
| (https://about.gitlab.com/handbook/handbook-usage/#why-
| handbo...).
|
| 2. Do not expect anyone to do anything you have not trained them
| to do. If you want your employees to work this way, _actually
| train them_ on how to do it.
|
| 3. Without leadership pushing this culture, it will. not. happen.
| Don't even suggest a change like this until you have sold at
| least 3 people in leadership.
| Xeoncross wrote:
| If you have a high-documentation culture, you must have
| documentation enforcer roles. It's crazy to think you would have
| a library without librarians to run it.
|
| There must be people who sole role in the company is to spend
| time on each team (in sequence) trying to follow or review their
| docs and get X running "like the docs say"
|
| This group of enforcers will contain a variety of people from
| tech, legal, customer service, and other backgrounds who can spot
| trash (in their area of expertise) when they see it.
| justin_oaks wrote:
| Unless the documentation enforcer has power, they'll just be an
| annoying voice. I don't care what that documentation enforcer
| has to say if my boss prioritizes code over documentation.
| You'd need management buy-in at every level for a high-
| documentation culture/company to work.
| Xeoncross wrote:
| Sure, replace documentation enforcer with security team. Same
| argument.
| [deleted]
| thenerdhead wrote:
| I wish more people adopted Andy Grove's thoughts on meetings.
|
| https://jondouglas.dev/lets-not-meet/
|
| This company seems to "get it" though. We ought to protect our
| attention more often.
|
| I'd take documentation over no documentation any day. Even if
| it's 4 years old and was last updated by a person who left for a
| competitor.
| DenisM wrote:
| I read through your link and it rang hollow to me. Care to
| share your insight?
| thenerdhead wrote:
| My blog is the insight. The book I recommend may give more
| context as to why it is important.
| pillefitz wrote:
| Many in this thread seem to conflate documentation with code
| documentation, while I use it as a means to communicate
| requirements to the developers. Some mockups here, some data
| description there, it makes all the difference. Our
| stories/tickets increasingly consist of only a title, a wiki link
| and some acceptance criterions. Works great for me as a PO, devs
| like it and provides a lot more context than fragmented tickets
| do.
| canucklady wrote:
| My current employer was sold to me as a "high documentation"
| place. What it means in practice is that if you're trying to do
| something there are 5 outdated documents describing the decision
| making process for how the project was run, and no documents
| about how to actually use the resulting software. Occasionally if
| you ask how to actually do a task in Slack someone will yell at
| you that you should have searched for a specific, obscurely named
| document in Google Drive, Confluence, or Github. We've tried a
| bunch of search tools which successfully surface the million
| product documents, design documents, PM reports, planning docs,
| retro docs and standup and oncall notes related to any feature,
| none of which are up to date.
| synu wrote:
| You really have to be religious about enforcing a single source
| of truth for any information and this gets a lot better.
| wpietri wrote:
| I think it's important to realize that a lot of documentation
| is duplication. It duplicates something expressed in code, in
| configs, in structure, in people's heads, or in the real world.
|
| Duplication _can_ be useful. But the more of it you have, the
| greater the maintenance burden is. (The main exception is
| documentation that is not supposed to be kept up to date, like
| a daily journal or blog posts.) So I think it behooves people
| to be very careful about adding documentation. Because as you
| say, it can turn 1 problem into n problems.
| gmd63 wrote:
| No, code actualizes the intent of the documentation and the
| product. The natural language description of a product
| shouldn't need to be discarded in lieu of some machine
| language.
|
| The lingua franca of ideas is natural language.
| simmschi wrote:
| Fair enough, but you still end up with 2 separate ways to
| express things. And I have yet to see a company that
| changes the documentation first and then derives code
| changes from that.
|
| Usually tickets are written, code is changed. Updating
| existing documentation is an afterthought at best.
|
| Personally I prefer any formal or semi-formal documentation
| (e.g. Swagger) over a Confluence page any time of the day.
| danny_codes wrote:
| I think most of us approach documentation without
| intention. We write to express the idea, but fail to
| consider how the documentation fits into the deliverable.
|
| For example, one could structure things where the English
| documentation is the deliverable. The code merely serves
| to actualize the document. In this world, we would
| consider the act of writing documentation of paramout
| importance, whereas the code is an implementation detail.
|
| I think software as a discipline is distinctly
| undiscipled about these sorts of concepts.
| hitchstory wrote:
| I built this documentation/testing framework to do just
| that: https://hitchdev.com/hitchstory
|
| I realized one day that the specs, tests and how-to
| markdown documentation I wrote all used the same
| examples.
|
| From that I derived the idea to create a "spec" DSL that
| could both be run as a test and generate markdown (with
| screenshots, etc.) to make nice high level how-tos.
|
| Cucumber has the same sort of idea but the DSL really
| isn't suitable.
| wpietri wrote:
| Sure. But where some see the lack of updates as some sort
| of moral failure, I think it's usually a sign that there
| is a process problem. The documentation was supposed to
| solve some sort of problem, but the fact that people
| don't update it is usually a sign that either it wasn't a
| real problem, that documentation wasn't the right
| solution, or that there's a broken feedback loop in the
| team's process.
| wpietri wrote:
| I am familiar with the notion that programmers are people
| who turn documents into code. I just think it's rarely true
| and even more rarely necessary.
|
| Personally, I don't think documents have intent. People
| have intent. Sometimes they write down some words as an
| approximate way to communicate their intent in that moment.
| But if there is a conflict between the written document and
| the actual intent, it's the human intent that matters.
|
| I also think that drift between written description and
| actual intent is good and desirable, because it usually
| means that the humans learned something about what actually
| needs to happen. So to the extent that documentation acts
| as leg irons for intent, I'm generally opposed to it. The
| faster our teams learn, the better the things we make.
| triceratops wrote:
| > Confluence
|
| There's your problem. The only use case for Confluence is when
| you want to hide information, but credibly claim that it's
| documented.
| SAI_Peregrinus wrote:
| We use Mark[1] to automatically create Confluence pages from
| Markdown documents in our git repos. So we can have a review
| process for documentation changes, the documentation of the
| code can be in the repo with the code, and yet it can still
| be accessed without having to give permissions to view the
| code repo! Helpful with a proprietary monorepo.
|
| [1] https://github.com/kovetskiy/mark
| triceratops wrote:
| So simple an idea, it makes you wonder why it's not already
| a core feature in Confluence.
| dosethree wrote:
| Bitbucket wikis basically do this.
| EFreethought wrote:
| > The only use case for Confluence is when you want to hide
| information, but credibly claim that it's documented.
|
| That describes Sharepoint more than Confluence.
| triceratops wrote:
| Sharepoint is what you settle for when you can't convince
| your company to spring for Confluence.
| bornfreddy wrote:
| Sharepoint is what you settle for when you hate the
| company, coworkers and yourself.
| cmdrriker wrote:
| Does it matter what tool you use to write documentation?
| Confluence gets a lot of sh*t because its in the grown-up
| camp of tools but I know people who've got problems even with
| nano.
|
| It's incumbent upon all users or members of the team to use
| the common tool along with agreed upon standards. Otherwise
| even if you wrote documentation in your own hemoglobin, no
| one would touch it either.
|
| Some manager prob chose _________ as the tool for ticketing,
| documentation, etc not because it was good at ______, or
| _______ but because it fulfilled their action plan to have
| something, anything in place so that if the universe goes
| supernova, well some stuff was written down.
|
| In my journey it seems that nobody is willing to criticize
| Edward Teach for the lousy treasure map he left, but rather
| we make fun of those who're still looking for his stuff.
| origin_path wrote:
| It does matter because the issue with wikis (not just
| confluence) is there's no approval or review workflow.
| Imagine trying to write a large program in which everyone
| could just commit at will, with no review process
| whatsoever, and where nobody had made any decisions about
| design up front. There'd be duplication, dead code, the
| organization would be crazy.
|
| That's the average wiki. It's a commons and a tragic one.
| To make docs work you have to treat it more like a
| codebase: clear ownership, standards, review processes,
| approvals, up front design, refactoring efforts etc.
| pxc wrote:
| There are some really nice git-based wiki systems out
| there, and one is built into GitHub and GitLab. If you
| want that type of workflow for your wiki, it's easy to
| get.
| abraae wrote:
| > To make docs work you have to treat it more like a
| codebase: clear ownership, standards, review processes,
| approvals, up front design, refactoring efforts etc.
|
| Maybe true in large orgs.
|
| But for smaller companies what I've seen is usually
| paralysis.
|
| e.g. someone notes a problem (maybe just a typo) in the
| doc. Can they fix it within seconds? If instead they need
| to raise a ticket then most likely it ain't happening.
| They move on, and the next person experiences the same
| problem.
|
| IMO the default should indeed be towards everyone
| committing at will. Yes that will result in the
| occasional snafu. Fix that when it happens. (obviously
| not good practice for the operating manual for a nuclear
| power plant - but for a <500 person Saas company it is).
| triceratops wrote:
| Ticket, or pull request?
|
| Mandating a Jira ticket for simple typo fixes is
| overkill. But if you make it easy to create a PR directly
| on the documentation file, without leaving the tab, I
| don't see an issue. This is already a Github feature.
| heydonovan wrote:
| Disagree. A ticket should be created for any change, no
| matter how small. It takes seconds to write a title, body
| and hit submit. I've seen those small ad-hoc changes
| cause havoc because someone forgot to escape a single
| quote or didn't realize tabs were necessary and replaced
| them with spaces.
|
| The default for Confluence is just that, everyone commits
| at will. There is no structure, tons of duplication, no
| standards when it comes to naming, formatting, audience,
| etc. I'm a huge fan of markdown/plain-text solutions,
| only because linters can be run that force you down one
| happy path. I don't believe Confluence has linters at
| all.
| The_Colonel wrote:
| > A ticket should be created for any change, no matter
| how small. It takes seconds to write a title, body and
| hit submit.
|
| A ticket represents a process (otherwise it has no added
| value over git commit message) and thus creates much more
| work than a couple of seconds.
| fsociety wrote:
| Ha I hear this a lot but the alternatives I have seen used
| are frankly just as terrible. I much prefer Confluence to a
| hidden web of Google docs.
| civilized wrote:
| Google Drive, the ultimate information black hole. Anything
| that gets sufficiently close will be sucked in and never
| seen again.
| edgyquant wrote:
| For my team we've switched to using GitHub markdown files
| with flowcharts: located within the folder containing the
| subsystem it describes.
| mnd999 wrote:
| Confluence is garbage
| Macha wrote:
| I'd take confluence over google docs because of how bad
| Google Docs' search is surprisingly
| triceratops wrote:
| Oh yeah it's not great either I agree. But the use case for
| Google Docs is somewhat different in my mind. It's good for
| collaboration and discussion, rather than a source of truth
| to describe "how things are right now". It's annoying if
| you can't find a particular document immediately but it's
| not the end of the world. Discussion on a Google Doc will
| happen for a few weeks or a quarter, then die down and the
| doc will seldom be looked at again. You might link to it
| from tricky parts of your codebase but it's not essential
| to a high-level understanding.
|
| Confluence and other wiki systems are clearly meant for
| longer-lived documentation and canonical information. You
| should link from or attach your working documents
| (spreadsheets, slide decks etc) to your wiki documentation
| for people to discover why certain decisions were taken.
| But if the wiki's discoverability is poor or it's not well-
| maintained or regularly reviewed, it's basically useless.
| matwood wrote:
| Interesting. Not that long ago we moved everything out of
| Confluence into Google Drive because GD search worked.
| Confluence search was horrible to find docs I knew were
| there.
| SgtBastard wrote:
| Confluence's search is so bad, it might as well be a
| Write Once, Read Never tool.
| radicality wrote:
| Not a fan of Google docs either, but I recently discovered
| CloudSearch which imo does a better job at searching Drive
| (and searches emails too, and few other places).
|
| link: https://cloudsearch.google.com
| l2silver wrote:
| Do you mean searching within a document, or searching with
| google drive? I've found that google drive search is
| incredible, they've done a great job of indexing
| everything.
| Macha wrote:
| They have no content excerpts in search results, so it
| doesn't provide any help for finding which result is the
| one you want.
|
| It also weights titles incredibly heavy, which combined
| with the previous part led to me not even noticing it
| searched the document body for years.
| PragmaticPulp wrote:
| Confluence (and all of the similar products) can be used
| successfully, but you need the teams to agree on and enforce
| a logical document hierarchy. It's not really difficult to
| organize a company wiki into teams, projects, and other
| logical divisions if you make it a priority.
|
| The primary failure mode I see is when people just throw
| random documents into Confluence wherever convenient at time
| of writing and never go back to logically organize anything.
| One symptom of this is when key information is being recorded
| in a hundred different people's "Personal Space"
|
| Taking even half a day to organize the average Confluence
| makes a huge difference.
| triceratops wrote:
| If using the lowest friction or default path in a tool
| leads to bad outcomes, that's a problem with the tool. Not
| the user.
| PragmaticPulp wrote:
| You create the lowest friction/default path according to
| your company's needs.
|
| There isn't a universal note taking application that
| comes pre-organized for your team's use case. You have to
| put some work into any tool you use.
| triceratops wrote:
| I disagree. The point of a tool is to reduce work.
|
| Most teams and companies aren't special snowflakes that
| need individualized organizations, and document
| hierarchies. There can be such a thing as sensible
| defaults that you customize or tweak later (no idea if
| Confluence ships with that - I've only ever seen
| Confluence installations in their already-screwed-up
| state). At the same time, an inexperienced user staring
| at a fresh Confluence install isn't going to get the
| organization correct right off the bat.
|
| If you have to put in work upfront before the tool is
| even halfway useful, it better be really damn good after
| that. Confluence is not.
| roflyear wrote:
| Yeah, I push back when people say "can you document that API
| you wrote in confluence?"
|
| It is such a stupid idea that it makes me question
| leadership.
|
| Some things are good to document there, but generally, if
| you're documenting code, you should do it in the code.
| rqtwteye wrote:
| I work in medical devices so we have to write a lot of docs.
| But they all disappear in document management systems where you
| can't find anything if you don't already know where it is. Are
| there no document management systems that are actually useful?
| wpietri wrote:
| Ask yourself how many document management systems are
| selected after rigorous tests of actual usage vs those
| selected after sales presentations and schmoozing. That
| should give you your answer.
|
| And if that's ambiguous, then ask how often your company
| penalizes people for making the common but wrong choice
| versus the uncommon but wrong choice.
| rqtwteye wrote:
| This applies to pretty much all enterprise software. It's
| rarely selected by or for the benefit of the actual users.
| Usually it's selected for the benefit of management (for
| example reporting) or for friends of management.
| contingencies wrote:
| _git_ works for us across business
| /electronics/electrical/mechanical/software.
|
| The exception is daily supply chain and accounting, which due
| to factors like urgency, multiple stakeholders per order,
| high pace of handover, external system integration,
| multilingual presentation requirements and nontechnical users
| we prefer a dedicated web based system with more of a real
| time focus with event hooks (eg. notification, translation,
| verification).
| rqtwteye wrote:
| What kind of docs do you have in git? Git doesn't work well
| with binary file formats like Word, Excel or Visio. You can
| do it but the diff won't work.
| yamtaddle wrote:
| A good secretary (or a bunch of them) and filing cabinets.
|
| _You_ may still not know how to find anything, but _they_
| will.
|
| Like a lot of other things, this has suffered from
| computerization making it _yet another_ small part of
| everyone 's job (which also increases context switching, the
| amount of shit you need to know and keep track of, and
| generally makes jobs more stressful) rather than a specialty
| that's the main focus of a few workers.
|
| The benefit (get to stop paying some employees) is easy to
| measure, while the harm is not.
| commandlinefan wrote:
| > 5 outdated documents describing the decision making process
|
| Would that place be the U.S. Department of Defense by chance?
| rfdave wrote:
| Not if there's only 5 documents.
| scottlamb wrote:
| Yeah, that sounds horrible yet familiar. Regarding this part:
|
| > Occasionally if you ask how to actually do a task in Slack
| someone will yell at you that you should have searched for a
| specific, obscurely named document in Google Drive, Confluence,
| or Github.
|
| When I'm the person being asked and know of the doc in
| question, here's what I try to do instead: I ask where someone
| searched for it. Then I update that place to refer to the
| correct document (and do some light refresh on the doc as
| needed). This works whether or not they tried to look before
| asking. If they did, well, now the next person who does that
| will just find it. If they didn't, I'm making them look before
| getting an answer. Maybe they find it, maybe they don't, either
| way I'll help them in the end if they're willing to look.
| nelsonic wrote:
| Having multiple systems for docs and Slack for follow-up
| questions is a major red flag. What you're describing is a
| billion dollar search product opportunity though. Most orgs
| don't have the discipline to have a single source of truth. So
| you end up with this mess. Run! Or ... fix it and then create a
| company to fix it for all the other orgs with similar data/docs
| siloes.
| futureproofd wrote:
| Do we work for the same company? :P
|
| Confluence has been the bane of my attempts in finding any
| relevant docs. Which one is the source of truth? Which one was
| a draft written by an overly eager to make a first impression,
| new employee (who is no longer with the company)? Don't even
| get me started on saving meeting notes to confluence.
|
| These days, I maintain my own knowledge base on Obsidian. If
| there's ever any confusion or request for more information
| within the company, I copy-pasta the relevant note from my
| obsidian bank to whomever person or whichever confluence page
| they deem the source of truth.
| neura wrote:
| So you are now the gatekeeper?
| whatshisface wrote:
| If an individual employee is going to put all that work in
| without being asked to or being given scheduled time to
| work on it they should get something in return.
| neura wrote:
| In the above scenario, I do not understand what they are
| getting in return.
|
| Are you saying this person should be hired/paid to store
| and retrieve the information being sought out?
| whatshisface wrote:
| Being as you put it the "gatekeeper" advertises their
| importance to everyone in the company who needs to know
| about the processes, making advancement easier and
| guarding against anyone thinking they are not necessary.
| nopenopenopeno wrote:
| Do you have any tips on how to maintain a developer's own
| knowledge base in Obsidian? I also use Obsidian but I
| currently use as more of a dumping ground.
| futureproofd wrote:
| It's actually quite simple even without using some of the
| advanced features: What I do is create a directory
| structure for each domain as I explore them. I.e.
|
| Toplevel: - Work -- Job A: -- Daily notes -- Services --
| Auth --- overview --- login flow -- Client -- Logger -- Job
| B: -- Daily notes -- Architecture -- node -- react -- etc
|
| (edit: sorry about the formatting)
|
| As the scope of your work expands, you add another sub-
| directory or file where necessary. Once it starts to grow
| in size, you can start making insightful connections via
| [[keyword]].
|
| Furthermore, you can pretty much take this knowledge base
| with you, wherever you go, by uploading the vault file to
| your google drive and accessing it locally via SMB.
| Automatic save/backup.
| ebiester wrote:
| I would suggest introducing two things.
|
| First, introduce The Diataxis framework ( https://diataxis.fr/
| ) for documentation. It makes people think about documentation
| in a more structured way, and allows you to be more specific in
| the types of missing documentation. (High documentation
| cultures are often good with explanation but not tutorials, for
| example.)
|
| Second, I would introduct the idea of a Documentation
| Portfolio. I have a review of Agile Documentation at
| https://www.ebiester.com/documentation/2020/06/02/agile-docu...
| and it speaks to another structure for how to build the
| documentation in a more reliable form and thinking more
| carefully about your audience for a particular type of
| documentation.
| crazygringo wrote:
| Diataxis looks fantastic. That chart on the home page is
| absolute gold.
|
| Thanks so much for the link, I wish I'd had that chart ten
| years ago!
| FooBarWidget wrote:
| What's the difference between Diataxis and the Divio
| documentation framework? https://documentation.divio.com/
| Whitespace wrote:
| Seems like the Diataxis author came up with the framework
| while working at Divio:
| https://github.com/evildmp/diataxis-documentation-
| framework/...
| joegahona wrote:
| Indeed, they look identical, even down to the font used.
| k__ wrote:
| Diataxis seems to be a fork of Divio.
|
| But according to the network graph on GitHub, Diataxis
| seems to be more active, although both of them still
| receive updates.
| lliamander wrote:
| The diataxis seems quite interesting.
|
| I see how it applies to documents which describe things as
| they are, but I'm curious how it would classify forward
| looking documents like technical designs, strategy and vision
| documents, roadmaps, and mission statements.
| c54 wrote:
| Diataxis looks interesting thanks for the link
| capableweb wrote:
| Wow yeah, it puts into much better words than what I've
| been trying to get software engineers to do for a decade or
| more. Really awesome resource, thanks again kind parent :)
| googlryas wrote:
| The nice thing about this as well is that, unlike a
| technical framework, you can start implementing many of
| the ideas of this framework without any sign on from the
| rest of your group. And if it works, what will eventually
| happen is people will say "wow, capableweb rights such
| fantastic documentation, we should go to them and ask for
| their advice on how we can all write documentation that
| good"
| mr_gibbins wrote:
| I'm sure these are great technological answers but this
| problem can be solved simply and quickly by a human.
|
| Not every issue needs to be solved by a butter robot.
|
| Why not employ a technical writer/documenter/whatever job
| title you like, even as a temp, whose sole job is to sort out
| the mess of documentation you have and then to write new
| documentation as you move forward?
| namdnay wrote:
| My experience is that for internal documentation the time
| spent explaining things to a technical writer is bigger
| than the time spent writing the documentation
|
| This isn't the case for external documentation, that has to
| be more polished, needs sign offs and images and demos and
| stuff - tech writers can come in useful here
| pmoriarty wrote:
| Most developers just don't like writing docs, are too
| busy to write them, and aren't very good writers anyway.
|
| So even on those rare occasions when they do actually
| document something, the documentation tends to be pretty
| bare-bones and not very readable.
|
| Good technical writers are worth their weight in gold.
| bazmattaz wrote:
| Having worked with software engineers for the last
| 10years I can confirm, most don't like documentation. At
| least 80% dont
| ericmay wrote:
| > Why not employ a technical writer/documenter/whatever job
| title you like
|
| Primarily because it's a far, far more complicated job than
| that and you can't really hire someone off the street to do
| it effectively. Typically in a tech company a tech writer
| is going to know almost as much or more (after years of
| experience diving into every detail) about a given
| technology or application or API, and so that begs the
| question why not make twice as much working as a software
| developer and not have to sort out these types of messes?
|
| Also job security. Anyone doing this work full-time is the
| first on the chopping block, and developers who are working
| on documentation tend to be perceived as lower status since
| they aren't delivering features.
| ghaff wrote:
| What you probably really want is a librarian (with some
| degree of technical background). We at least had one for
| a while for our sales/marketing docs--which are separate
| from customer-facing technical docs.
| spoils19 wrote:
| > you can't really hire someone off the street to do it
| effectively.
|
| I disagree, I've been apart of a few companies that have
| done exactly this. I would suggest not presenting this
| argument as an absolutism.
| CrypticShift wrote:
| Summary: HIGH Documentation = HIGH staleness + HIGH loss.
| HIGH staleness is because nobody wants to do it (status
| is lower). Also... nobody else can do it (full
| understanding of what is being documented is needed)
|
| So, to solve the first staleness part, there is only two
| ways: raise the documenter status, or make it possible
| (easier?) for someone else to do it. are they both really
| that hopeless?
|
| PS: to solve the second loss/discovery part, I think we
| are heading for that AI powered simple "unified search"
| experience.
| jrochkind1 wrote:
| what's a butter robot? (I feel like i'm setting up a
| punchline for a joke somehow...)
| spydum wrote:
| Probably a text to speech fail (edit: errr speech to
| text). Bot or robot == butter robot
| FridgeSeal wrote:
| It's a reference to this: https://youtu.be/X7HmltUWXgs
| sdflhasjd wrote:
| It's actually hilarious how Google - a company famous for it's
| search engine - made Docs, who's search function cannot find
| anything.
| crazygringo wrote:
| I live and breathe using Google Docs search functionality.
| It's my main way of finding files scattered across 10 years
| of folder hierarchies. It works great.
|
| What do you mean it can't find anything?
| sdflhasjd wrote:
| What I find is that it's very "dumb", almost "... WHERE
| filename LIKE '%query%'" dumb. Example might be searching
| for "<Cool Project> Technical Spec".
|
| - Can't find "Technical Specification" in the "<Cool
| Project>" folder.
|
| - Can't find "Tech Spec" (and vice versa)
|
| - Can't find "<CoolProject>"
|
| Is there some "enable real search functionality" checkbox
| I've missed, or am I just doing it wrong?
| crazygringo wrote:
| Yeah, I think you're "doing it wrong" as much as I hate
| to say that, sorry.
|
| Search is keyword-based, like large-scale search is
| pretty much anywhere. Expecting "specifications" to match
| "spec" is expecting too much, same as expecting half your
| search to match a folder and the other half to match a
| file the folder is in.
|
| The main thing to keep in mind is that search is content-
| based, not just filename. So instead, search for _key
| terms_ you think are _in the file_ , as opposed to
| focusing on folders/filenames. Start with one or two,
| then modify or add as necessary to narrow down.
| mnd999 wrote:
| And it's still miles better than Confluence.
| coffeeblack wrote:
| Very much my experience too.
|
| People need to actually learn how to write and maintain(!)
| documentation, otherwise it's just a huge chaos.
|
| Rule 1: less (text) is more.
| gmd63 wrote:
| Lack of organization to that degree is an indicator of failed
| leadership
| EFreethought wrote:
| > you should have searched for a specific, obscurely named
| document in Google Drive, Confluence, or Github
|
| Are people at the same job telling you to check 3 different
| sources for internal docs? Maybe that is the main issue. Put
| knowledge in one place.
|
| More specifically: One place that is not Sharepoint.
| baby wrote:
| Sometimes (often?) an outdated document is still great and
| useful and much better than no documentation at all
| zeroonetwothree wrote:
| Equally often it's worse and a waste of time. And you won't
| know which world you're living in for a while.
| baby wrote:
| I've yet to find an outdated doc that makes the situation
| worse (unless you assume it's correct and up-to-date, which
| you should never do with anything anyway). There's a reason
| we like RFCs even if they only represent a decision in
| time.
| nonethewiser wrote:
| > My current employer was sold to me as a "high documentation"
| place. What it means in practice is that if you're trying to do
| something there are 5 outdated documents describing the
| decision making process for how the project was run, and no
| documents about how to actually use the resulting software.
|
| How is this not inevitable if your goal is to always write
| things down? It seems like the way for document to be accurate
| is to keep the scope small and if you want everything in scope
| then it's going to contain a lot of outdated information.
| ghaff wrote:
| You basically need to deprecate and eventually probably take
| offline outdated docs. There's something to be said for the
| historical record but if it's indexed--and if it's not no one
| will probably find it--it's going to compete with current
| documentation for search.
|
| There's no easy answer.
| enraged_camel wrote:
| Large organizations in many sectors employ professional
| records managers for this reason (and many others). Every
| record has a "lifecycle" and it is deprecated and discarded
| after that.
| civilized wrote:
| From my perspective, calling yourself a "high documentation"
| org leaves a similar impression as calling yourself a "high
| code" org.
| BurningFrog wrote:
| Everyone wants accurate updated documentation.
|
| Nobody knows how to accomplish this.
|
| Whatever the solution is, if one exists, I'm sure it involves a
| lot of work keeping documentation up to date.
| ramesh31 wrote:
| This is why I find documentation to be either useless or
| actively detrimental. Your documentation is the code. Unless
| you have a dedicated technical writer on the team whose full
| time job is to work with developers to document their code, it
| all just becomes an outdated confusing mess immediately.
|
| Obviously this doesn't apply to public facing codebases. But
| trying to keep an internal codebase documented, other than
| fully finished self contained library level code, is a
| sisyphean task.
| convolvatron wrote:
| that's ok. but expect your onboarding to take a really long
| time.
| atom_arranger wrote:
| Agree. If possible the documentation should live in / be
| generated from the code as well.
|
| I'm not checking confluence, write it in a ".md" file in the
| repo if you want me to see it.
| Reimersholme wrote:
| gautamdivgi wrote:
| There are docs and then there are Docs. I think documents
| should be treated as source code. Go through a proper PR
| process so that you know what the latest and greatest is.
| Maintaining a wiki is one of the worst ways to document. It
| just creates a sprawl that is hard to control. I deal with it
| on a daily basis but have had little success with getting my
| team moving to our source control system for documents.
| znpy wrote:
| We might be colleagues then.
| narrator wrote:
| The way I did this at a company I worked for is that we had a
| MediaWiki. That's the software that runs Wikipedia. Whenever
| anyone would ask me a question, I would make a MediaWiki page
| or add to an existing page and appropriately link the page or
| entry to other relevant pages and answer the question there.
| Then I would send them a link to the MediaWiki page. This was
| super efficient. Whenever any documentation was wrong, I would
| update it.
| michael1999 wrote:
| +1 for all docs being public-by-default. But these are all
| sophisticated skills. And the broader industry does not reliably
| teach them.
|
| ctrl-F "Training" 0 hits. ctrl-F "Hiring"
|
| > But we take great care during the hiring process to choose
| people that thrive under these conditions.
|
| Is the interview by post? There's a story here, but I don't know
| what it is.
| intelVISA wrote:
| Recently I've only worked for companies with limited (1 max)
| meetings for ICs a week, I definitely recommend it.
| pigsinzen wrote:
| Is the lack of "meetings" offset by pair-coding, dragging out
| synchronous conversations in Slack, or otherwise controlling
| engineering time and schedule?
| intelVISA wrote:
| No, (currently) fully async as long as deliverables are met.
| The extent of 'controlled' engineering time is requiring 1x
| code review from a different SWE to merge a PR which is also
| async via GitHub comments.
| pigsinzen wrote:
| Ahh nice! I was recently on the market and had nearly no
| luck finding a culture like that which matched my skill-
| set. I am envious.
| intelVISA wrote:
| It's still quite rare unfortunately, and there are still
| negatives: less time in meetings means more time actually
| working which isn't always what you want!
|
| Though it's offset by very generous comp as there's not
| as much bloat to soak up your TC. So YMMV...
| holoduke wrote:
| Documentation is worse than code. It's often outdated, difficult
| to understand and full of useless information. In every company I
| have been people hate to read docs and nobody wants to maintain
| them. I am not sure what a good alternative might be.
| dist1ll wrote:
| That's a culture problem. It boils down to documentation being
| a second-class citizen which is not included in the "definition
| of done".
| KaoruAoiShiho wrote:
| It just needs to be better than meetings to be well, better
| than meetings. Nothing is worse than meetings.
| maximus-decimus wrote:
| I was watching a DistroTube video where he was ranking multiple
| windows managers, and he explicitly refused to give i3wm points
| for having great documentation because "it's the bare minimum".
| Except all the other ones had crap documentation.
|
| One can only dream everything had documentation as great as
| i3wm's as a bare minimum.
| nesarkvechnep wrote:
| I thought high-documentation would be related to literate
| programming. Joke's on me, looks like we're going to try to
| reinvent LP forever.
| cokeandpepsi wrote:
| to many meetings -> not getting enough done -> hiring spree ->
| even more meetings -> reorgs to nowhere -> layoffs
| glonq wrote:
| I had the luxury of being able to document the hell out of the
| previous system that I worked built -- before, during, and after
| development. It was a refreshing change from 'just hurry up and
| build the damn thing'
| bergenty wrote:
| As someone that hates taking a long time to write documents and
| has similar resistance to reading large technical documents I
| much prefer to ask my specific questions in meetings. I retain
| the information much better that way.
| civilized wrote:
| My experience with meetings is that they're effective at
| getting people to nod their heads and say they get it, but when
| it comes time to actually do something, they'll be back at the
| expert's desk needing to go over it again.
|
| Then again, documentation doesn't necessarily solve that
| either, because then you have the people at your desk who don't
| read the documentation and need someone to walk them through
| it. But at least that way you don't have to go from memory.
| kozak wrote:
| "Unfortunately, Tremendous is not available in the country where
| you are located. If this is a problem, please contact
| support@tremendous.com."
|
| I'm in Ukraine and this is disgusting.
| cateblanchett wrote:
| US treasury department regulations prohibit US companies from
| working with people and companies in Russian-controlled parts
| of Ukraine. Unfortunately, IP geolocation is accurate only to
| the country level, so US companies have no choice but to block
| the entire country to comply with regs.
| kozak wrote:
| This is the first case I know of. I never get such issues
| here in central Ukraine. This is because occupied regions
| always present themselves as Russia, not Ukraine. If
| something says that it is Ukraine, it's a sure sign that it
| is NOT occupied by Rissua.
___________________________________________________________________
(page generated 2022-11-22 23:00 UTC)