Hi All, I would like to find out what users think about project documentation. Given the current doc system (i.e.

kedro build-docs

) will be discontinued with version 0.19, I wonder if a plugin should fill its place. @Asch Harwood suggested that there is a need for communicating with non-technical stakeholders - are there more users thinking this way? Would a plugin that assists with the creation of documentation be useful? In order to aid discussion, I played around with a prototype static site as an example for project documentation. I used the Kedro spaceflight tutorial project as a base, and you can explore the finished documentation here. Given that the Kedro framework defines much of the information needed for project documentation, I think it would be pretty straight forward to create a plugin that would: - create the basic documentation structure - fill in details about pipeline, nodes, data and parameters automatically - insert an interactive Kedro-Viz graph - provide empty templates for additional notes to write - example how to publish as a static website, for example to GitHub Pages Just to clarify, this is not a plugin, just a "fake" output for discussion. I would like to find out if: - such a plugin would be useful - maybe find a few projects other than spaceflight that could be used during development/specification - get clarity on desired functionality - maybe some collaborators interested in making it If you want to find out more you can also clone the project repo. There are instructions in the manual how to build the docs locally and use them. Leave your feedback either on slack or if concrete ideas, please create issues in the repo. Looking forward to hearing from you Sean

This is super cool!

@datajoely - Glad you like it. What do you mean by "what dbt do here". What is dbt?

dbt is a bit like Kedro for SQL https://github.com/dbt-labs/dbt-docs

yes - heard of it. Not used it though.

this would be super cool idea : )

I havent had a chance to look at this, but Kedro build docs has been a big draw for us

@Sean Westgate could I ask you to put this in an GH issue? Shouldn’t be much work, just copy and paste and we’ll have a good opportunity to discuss at the next backlog grooming

@datajoely - ok - will post as GH issue. Let me know what comes out of the internal discussions. I assumed that with core team priorities already set for 0.19 there might not be many resources available for this, hence seeing if there is appetite within the community. But it'd be amazing to get some support, especially around what it would need to do. Do you have any metrics how important

kedro build-docs

was for users? And if so, what did they like and what were the pain points? I am fortunate to have some spare time at the moment so ping me if you need anything or have any questions.

so the reason why it’s been deprecated is that it was barely used

Yes - I'd be interested to take part. I saw the route to become a maintainer, but at the moment I am not sure I could make a more on-going commitment. Plus I am pretty new to Kedro. But I'd be happy to join to discuss the docs project.

💪 amazing either way - just posting for the community to see 🙂 Thanks for kicking off the topic, I really love your prototype

@Sean Westgate You can find more concrete data about the usage of

kedro build-docs

and some of the other command we’ll be deprecating in the research write up: https://github.com/kedro-org/kedro/issues/1293

Thanks @Merel - FYI here is @Sean Westgate’s issue: https://github.com/kedro-org/kedro/issues/2075

@Merel - thanks for the link to background info on CLI usage. Very interesting and I really like your

build-docs

conclusion: users like it, but don't use it. Is this because they don't need it (not part of their workflow) or because it doesn't do what they would like it to do? Chicken? Egg? The eternal product management conundrum...

I think it’s a bit of both. Some just don’t find a good use case for it and others find it doesn’t fully do what they want it to do. Doing docs well is also really quite difficult! The Kedro team is going to look at other ways to build the Kedro docs, because we don’t find

spyinx

that user friendly. So it’s also tricky to recommend a command that uses a tool that we don’t even like ourselves 😅

Haha - yeah. I tried

sphinx

several times and didn't get very far. This is why I used mkdocs for the prototype. You should check it out for your main docs. It is just fun to work with - so you can just focus on the writing.

Thanks to everyone for their thoughts. I read the kedro issue on the user research and just want to bring up something here • there seem to be large differences in the amount of calls of certain CLI commands on which you base your decision whether "is this needed or not". however, the amount of calls may not be the right KPI for this if a command is crucial but not obligatory on every run • do you know something about your sample? different users use different commands in a given timeframe, and they do not have to represent your entire user base. How many 'one time and never again' users hammered out some 'kedro run' before ditching kedro altogether? how many calls got "kedro package"? Iam looking forward to the further enhancements of doc related functionality either way; the inclusion of kedro viz would be really nice.