Replies: 4 comments 5 replies
-
I do agree with this premise. What I've found over the past month and half that I started working for Red Kubes is that there is no real clear documentation on how to get started. Some documentation is generally missing, other documentation must be "inferred" from external resources, and there is no clear path for development. For onboarding, or sharing our development stack - which is useful if we want input from the community (open source 'n stuff), then it would be wise to document what applications are necessary to install, what extensions etc. I know that for VScode there is already a file that suggest extensions and that's a great start. But for the brew aspect, what applications do I need?
There's a couple more that I installed because I prefer that, and maybe this list is too long or contains non-required applications. Then the next part would be the documentation on the requirements, that is being discussed in #300 so thank you for that. Next step for me, and where I'm missing documentation is on where to start for development. I need to create a chart, where to look, what to create. Maybe document the important folders that could require modifications/input, like chars, values, possibly helmfile.tpl etc. Having a single source of truth in regards of documentation would be helpful, as now I am not sure where to look for which kind of documentation. Making the process of finding what I need more tedious. If we could centralize the documentation and extend it, it would become a great resource for me, new hires and possibly the open source community. |
Beta Was this translation helpful? Give feedback.
-
Look, I don't want to kill your enthusiasm, and appreciate concerns being addressed. Documentation is always bad and lagging behind, however you approach it. It is true that the above idea holds value, I am just worried about architecting a huge tower of overhead and taking on the debt of keeping all those areas addressed. Lets stay focused and identify current pain first and see what is needed:
We will however see all of this as work, and for that we use scrum and have prioritization. Always align with the bigger process and don't let yourself get carried away in large discussions and suggestions. There is work to be done and features to be delivered. |
Beta Was this translation helpful? Give feedback.
-
I thus want to ask you to create issues with label |
Beta Was this translation helpful? Give feedback.
-
I find this discusson confusing, as it started addressing otomi.io documentation, but then continued on I think we should moderate these "discussions":
|
Beta Was this translation helpful? Give feedback.
-
Proposal for new documentation system
I propose to write the documentation that was never written. I sincerely believe this holds true:
"It doesn’t matter how good your product is, because if its documentation is not good enough, people will not use it. Even if they have to use it because they have no choice, without good documentation, they won’t use it effectively or the way you’d like them to."
This is an excerpt from (what looks to me) as a fantastic resource to continue documenting: https://documentation.divio.com/introduction/. Please check out this resource for more in-depth clarification.
Its premise is to divide documentation into 4 (four) subcategories:
I propose we agree with the premise, merely because it gives us an easy system and framework to write better documentation while at the same time making it easier to maintain. If not, I would appreciate a clarification of what system we're currently using and why it's superior.
Furthermore, even if the status quo is more valued, I still have a personal belief that our documentation is not up to standards, merely because we haven't written a lot and the product is still difficult to use as a new user. It is also not unreasonable to assume that it is currently difficult for developers to understand "how to write, and what to write, and where to write it", referring to all the discussions we have about the topic, and it would save us a lot of hassle if we could simplify the system and all become more effective documentation authors.
If we agree with the premise, let's discuss how our documentation looks like and could look like with this framework.
Overview: types of documentation
Let's start with navigation. It will be wise to also include an index of what we already have so we don't have to re-invent the wheel on some topics. We can loosely categorise our current documentation into tutorials, how-to guides, reference material and explanations.
I will argue that some of the documentation has multiple roles, which might be an anti-pattern. I will put those in a shared category "A+B".
Furthermore, I also included some documents that might not be fully considered our documentation, but I think it helpful to gather everything in one place first of all.
For definitions I defer to the documentation resource.
Tutorials
How-to guides
Reference guides
Explanations
Documentation type overlap
The tendency to overlap does not actually magically appear. There is an explanation for it: https://documentation.divio.com/structure/.
For our use case the following holds:
"tutorials and how-to guides are both concerned with describing practical steps"
It is therefore reasonable to put them together. However, because they do not adhere to a structure, they can become confused.
https://otomi.io/docs/installation/*
Inferring from the header "installation", the resource wants to be a how-to guide, but it mixes tutorial elements. My main concern is that this is the gateway for new users to start using Otomi, and it assumes too much pre-knowledge, so users might become confused.
https://github.com/redkubes/otomi-core
It lists the features of Otomi, which is part of the reference. Then it has a how-to guide with instructing development. It also has some tutorial elements where it teaches the user to target specific deployments.
Main concerns
Before dismissing the proposed system as a mere anecdote, here is a list of substantial projects that make use of this structure:
For a full list, see: https://documentation.divio.com/adoption/
A lack of tutorials
Whether you agree with the premise in this document or not, it is reasonable to assume that there isn't a clear learning path for a new user to start using Otomi. If we don't do anything else, lets at least put some effort into this part. #173 will probably be a decent start, but it's not enough. I also propose to make the following changes:
Documentation is spread out
Simply indexing all of our current documentation like I did in this discussion might already be a bit helpful for a breadcrumb trail. However, I would also like to see this system implemented. Now this part might be a bit politically sensitive within Red Kubes. I'm personally more of the extreme side, and if it were up to me we would adhere to this structure on Otomi.io. We would then reference to the current documentation in the Github repository, but for future documentation, it would be better to maintain everything externally. It's not only that our documentation is roaming all the repositories, but including it in one central place will massively reduce the errors made by project maintainers.
Lack of documentation in general
Lack of documentation in general motivated me to start this discussion. I will create a proposal of all the documentation that still would need to be written in this discussion: (I will add a link soon). Suffice it to say that I would like to adhere to this system. It provides an adequate and practical strategy to structure what documentation is missing. I hope it's obvious that I needed to outline the proposed system first to create a proposal for new documentation.
Note that a more simple way of structuring documentation is not only for ourselves but for future selves, future maintainers and new users.
tl;dr
Beta Was this translation helpful? Give feedback.
All reactions