Sean Westgate
11/28/2022, 3:42 PMkedro 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
Seandatajoely
11/28/2022, 4:10 PMSean Westgate
11/28/2022, 4:13 PMdatajoely
11/28/2022, 4:14 PMSean Westgate
11/28/2022, 4:16 PMNok Lam Chan
11/28/2022, 4:26 PMAsch Harwood
11/28/2022, 8:23 PMdatajoely
11/29/2022, 9:34 AMSean Westgate
11/29/2022, 9:58 AMkedro 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.datajoely
11/29/2022, 9:58 AMSean Westgate
11/29/2022, 10:06 AMdatajoely
11/29/2022, 10:07 AMMerel
11/29/2022, 10:51 AMkedro build-docs
and some of the other command we’ll be deprecating in the research write up: https://github.com/kedro-org/kedro/issues/1293datajoely
11/29/2022, 10:59 AMSean Westgate
11/29/2022, 11:08 AMbuild-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...Merel
11/29/2022, 11:13 AMspyinx
that user friendly. So it’s also tricky to recommend a command that uses a tool that we don’t even like ourselves 😅Sean Westgate
11/29/2022, 11:17 AMsphinx
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.Sebastian Pehle
12/09/2022, 3:00 PM