10 ms·
I would suggest introducing two things. First, introduce The Diataxis framework ( https://diataxis.fr/ https://diataxis.fr/ ) for documentation. It makes peopl
by ebiester 4y ago
I would suggest introducing two things.
First, introduce The Diataxis framework ( https://diataxis.fr/ 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-documentation-takeaways.html 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.
- c54 4y agoDiataxis looks interesting thanks for the link
- capableweb 4y agoWow 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 4y agoThe 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"
- crazygringo 4y agoDiataxis 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!
- mr_gibbins 4y agoI'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.
- FooBarWidget 4y agoWhat's the difference between Diataxis and the Divio documentation framework? https://documentation.divio.com/ https://documentation.divio.com/
- joegahona 4y agoIndeed, they look identical, even down to the font used.
- k__ 4y agoDiataxis 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.
- sidpatil 4y agoFrom the GitHub page, it looks like Divio is actually a fork of Diátaxis. divio/diataxis-documentation-framework is forked from evildmp/diataxis-documentation-framework, and evildmp is Daniele Procida, the creator of the latter repository and the maintainer of diataxis.fr.
- k__ 4y agoThanks for the investigation!
- Whitespace 4y agoSeems like the Diataxis author came up with the framework while working at Divio: https://github.com/evildmp/diataxis-documentation-framework/issues/43#issuecomment-1017745749 https://github.com/evildmp/diataxis-documentation-framework/...
- lliamander 4y agoThe 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.
- q7xvh97o2pDhNrh 4y agoWhoa! I love a good 2x2, and the one on the Diataxis home page is great! Adding a caption here for anyone on a screen-reader, before I give commentary on it: * X-axis: "serve our study" vs "serve our work" * Y-axis: "practical steps" vs "theoretical knowledge" * which gives 4 quadrants: how-to guides, tutorials, explanation, and reference So I'm joining a new place recently, and it's another one of those "documentation-heavy" places where (of course) every new hire conducts the ceremonial ritual of updating the docs wherever they could use improvement. I really like having this ontology in my head now; I can see it being very useful. Also, I wonder if the relative distributions of each one could tell you something about the team's health — or even just the kind of work the team does? For example, between two teams who are both documentation-heavy, what does it means if one team's docbase is 80% tutorials, whereas the other team's is 80% reference guides? It would be fascinating if anyone's already given thought to relative metrics/heuristics like this.
- ebiester 4y agoAlmost every developer I've ever seen defaults to "explanation." Reference is there to the extent that it can be auto-generated, but most companies are relatively light on reference. Tutorials are pretty rare in smaller orgs - it rarely gets prioritized. How-tos are an interesting case. I see a lot of informal how-tos in slack. However, how-tos also are the most likely to become stale because if they're needed often enough, they tend to become automated in part or whole. It is by its very nature transitory.
- throwaway290 4y agoThis does not help with outdated docs.