6 ms·
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 rob
by mr_gibbins 4y ago
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 4y agoMy 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 4y agoMost 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 4y agoHaving worked with software engineers for the last 10years I can confirm, most don’t like documentation. At least 80% dont
- still_grokking 4y agoWhich is a funny statement as almost all devs like to have documentation.
- nmfisher 4y agoIf I'm simply consuming a library, I find most real-world documentation to be pretty superfluous. A full working example is usually enough to understand how things fit together. If I'm working on a library, design docs and commented code is nice though.
- akonbinator 4y ago
- dividefuel 4y agoIt may take more time to explain it to a tech writer than it would for you to write it, but in most cases the final docs written by a tech writer will be much better.
- euroderf 4y agoThe tech writer's output will be a Force Multiplier.
- ericmay 4y ago> 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 4y agoWhat 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.
- CrypticShift 4y agoSummary: 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 somewhat possible (easier?) for someone else to do at least a part of 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.
- euroderf 4y agoA feature of docs-as-code is having the (typ. markdown) docs live in the code directories. Leaving no excuses for tech people not to update them, or at least insert a TODO. Another idea might be, whenever a new feature is closed out, auto-allocate some percentage of its implementation time to documentation, and schedule an interview with a tech writer.
- beckingz 4y ago
- jrochkind1 4y agowhat's a butter robot? (I feel like i'm setting up a punchline for a joke somehow...)
- spydum 4y agoProbably a text to speech fail (edit: errr speech to text). Bot or robot == butter robot
- FridgeSeal 4y agoIt’s a reference to this: https://youtu.be/X7HmltUWXgs https://youtu.be/X7HmltUWXgs
- biztos 4y agoHaha that’s awesome. I had figured it was just a typo for “better robot.”
- thegabriele 4y agoSince the last episode we have also a lever robot
- daeminsong 4y agoThanks for asking this. Was too afraid to ask haha.
- mr_gibbins 4y agoSorry, should have been clearer - butter robot from Rick and Morty. An entity who has one menial job to do and that is the reason for their existence. In this sense it was meant that the technological solution - auto documenter tools, etc - they're the butter robots. I was making the point that rather than just shim Yet Another Tool into the stack to do a single but important job (pass the butter / write the docs) perhaps give it to a human who will a) do a much better job and b) reduce the complexity of the stack. Apologies for the confusion. I'm surprised how this comment thread took off. Looks like there's plenty of support for AND against. I simply meant to make the point that for some problems humans do better than machines and it can be more efficient in the long term to look away from a tech solution to a human problem.
- matai_kolila 4y agoEr, the butter robot joke was a throwaway line about the exential crisis of a robot that carries butter, not a blueprint or metaphor about how to conduct software development, please for all that is holy don't try to read more into that than is there...
- ebiester 4y agoI’ve advocated for hiring a librarian but I haven’t ever been able to make the case successfully. So yes, I agree with you, but the “how” of structuring and the “who” are orthogonal. This is about prioritizing the documentation you write.
- andrewflnr 4y ago> I'm sure these are great technological answers They're not, actually, as is obvious if you actually read the links. They're human process approaches.
- thatwasunusual 4y ago> Why not employ a technical writer/documenter/whatever job title you like Who would supply that person with the information required to write the documentation?
- innocentoldguy 4y agoSubject matter experts, to the extent that the writer isn't one already. In my opinion, companies should hire subject matter experts who can write rather than just someone with an English degree. I've fixed a lot of terrible documentation written by English majors with no engineering background.
- mrmrcoleman 4y agoI came here for the butter robot.