-
Notifications
You must be signed in to change notification settings - Fork 8.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[discuss] Future of Developer Documentation #41833
Comments
Pinging @elastic/kibana-docs |
Pinging @elastic/kibana-platform |
Pinging @elastic/kibana-app-arch |
👏 Well done, Josh! The problem is well-defined and the solution is well-reasoned. I support this proposal.
If we can get this part working, I think we'll have a great DX. Or should I say WX (writer's experience). |
+1 |
This is great and solves an entire category of problems we are facing in terms of developer experience. (Are my answers in the Migration guide? The Contributing guide? Styleguide? elastic/docs? Random markdown files in the source? Some other internal Google Doc? etc) It also feels like something that we could accomplish with a reasonable amount of effort since we aren't completely starting from scratch. I'll be especially pumped if TSDocs extraction becomes a reality ❤️ |
I'd like to include "How to write functional test?" in Kibana contributor documentation |
I think these are all great efforts, but I'd like to bring up an additional option that I feel addresses two main aspects.
I have been working on an idea of One downside with this model today is discoverability. Everyone comes to me to ask about how embeddables work, and I point them to I'm not sure how helpful this is, but I also expose the actual code snippets that are backing the examples, which guarantees that the code samples I'm showing are up to date and working. Someone updates the code, the code snippet is automatically updated. I am bringing this up on this issue because I'm struggling with the thought of having yet another duplicate source of information in the textual parts of this code. For example, the data services entry: I copied from the readme Which made me think, well I could just paste the README's directly in there, maybe even using an EUI markdown widget. However the links likely wouldn't work then bc the links in github READMEs are relative, here they'd need to be absolute. I could probably find a workaround to add the prefix for any relative paths I suppose. Another cool aspect I could implement in this "developer documentation mode" of Kibana -- having an action on embeddables that gives you the code snippet you would need to embed any given embeddable in your own application. @smith was just talking about how it took a lot of time to create a visualization to embed in a solution, and how much easier it was to use Kibana to build that visualization - all we need then is the "export code snippet" step that shows exactly what you'd need to paste into an app to render that embeddable. So, my questions are:
|
Developer audiencesI don't think we can break down our developer audience into just "Plugin developers" vs "Kibana developers". I think it's more fine grained:
To make it easier to refer to these different audiences, I'm going to create shorter names for them:
The questions we need clear answers toIn order to solve the goals Josh listed above, we need clear answers to the following four questions (which is more fine grained than "Where should dev docs live?"):
What language should this documentation be written in?What language should this documentation end up as?Where should this documentation be written?Where should you to go learn about something?Linking sources of truth from different locationsWhat do we need to do to get to the above vision?
Long term, we can still use this setup to transition to an improved online system for our api documentation. Short term, we'll still have this content hosted online. |
Condensed version of the above: SummaryWhere should I write information?
Where do I find, or learn about this information?If you work for Elastic, start in the |
@stacey-gammon Thanks for breaking this down! This looks great and makes sense to me. I have one suggestion. Can we present this information in a simpler way? In my experience, the simpler something seems, the easier it is to understand, and the more likely people are to use the information. For example, I'd suggest making these changes to simplify this info:
Roughly, here's what I'm thinking the result would look like. WDYT? In-source docsInline commentsWhen documenting low-level implementation details and intentions, use inline comments alongside the code being documented. For example, specific functions, type definitions, and algorithms. Root-level READMEsHigh-level documentation for a plugin or its modules should go in a root-level README in the directory that encapsulates the plugin or module being documented. Out-of-source docs
|
@stacey-gammon ++, what I like about this is we organize our existing doc mechanisms into a consistent whole, and make it easy to navigate and understand. I think there is lot of mileage we can get from just doing that. @cjcenizal agree on simplicity, I think with a few iterations we can get to "easy to navigate and understand" I'd distill the above comments into. If you are writing, think about the level of abstraction and your audience, and choose one of these 4 places, from lowest to highest level:
The underlying idea is the best place to store documentation is on the documented thing itself, or as close as possible. Each of these might have sub-locations and specific guidance in terms of doc language and process, and that is OK it lets us optimize for each location. While I agree with @cjcenizal that maybe we don't mention the team repo in public docs, I think the team location should be top of mind. I'd argue that our most important audience at the moment are all the Kibana contributors at Elastic that aren't on the Kibana team, and it happens to be an internal audience. Knowing things like "who do I talk to" for example. |
I don't think we should over qualify this. Some plugin-level documentation is better to break up into multiple docs, rather than keep in a single README. Example: https://github.com/elastic/kibana/tree/master/src/plugins/embeddable/docs
I don't think we should add
I like this simple 4 list breakdown! Only one thing, 3., "product" makes me think of the user facing docs, which go in
I actually do think it is important to call out the language and specify asciidoc. It will lead us towards consistency, remove a point of confusion, and it's necessary to create an online, searchable, holistic view from our online hosted documentation. I think it's fine to get there incrementally, but specifying the end goal/vision, is helpful, imo. For example, I kept going back and forth on a PR I made converting CONTRIBUTING.md to asciidoc because I was worried we'd end up choosing Markdown as the language of choice and I'd have to undo all those changes. Having a clarifying statement, that this kind of documentation should be in asciidoc, will unblock me. |
I'll leave this issue open till the end of the week for any more comments. If nothing big comes up, the plan forward is:
|
I think from the latest comments in this issue a separate "book" is no longer the strategy. Just in case it is, however, please note that we're actively working on an extensive documentation redesign that moves away from our current book-focused product-specific docs. Instead, we're organizing content around our 3+1 solutions and then further grouping it based on the user-role and content type. We don't have any external links yet, but I'm happy to chat further if you have any concerns about how this affects the trajectory of the developer documentation. |
I think, with the recommendations we are proposing, we could do either (a separate book, or inlined)? Short term, I was just going to inline them, to keep the We may have to refactor the number of Does asciidoc have a way to use that as a variable? so you could do something like:
And {dev_guide} could be either an empty string, if it's a top level book, or Maybe there are other concerns/issues though that I am not aware of! |
There are indeed cool ways of manipulating the nesting of pages without altering the pages themselves: leveloffsets. I think this is something we're hoping to move to across the library in general (i.e. controlling the navigation/nesting at the highest level of the tree, not down in the leaves/pages). I've been using these offsets lots in my prototypes, so I'm happy to help if you want further implementation assistance. |
As part of the initial move to
Ideally we include every plugin in this table, even if there is no documentation. I think this helps with discoverability of what's available to developers. |
+1 @joshdover! I could see that going under the |
Slight change, the directory for dev docs will remain where it is now at:
instead of Otherwise, the plan remains the same and the initial PR to head towards it has been merged. Will go ahead and close this! |
This issue was brought up about a year ago (warning: contents may be hot! 🔥). I'd like to propose a long-term plan for the future of Kibana developer documentation that incorporates many of the ideas discussed previously along with new concerns and things we've learned in the past year.
Goals
Before jumping into the details, I think it's important to state the goals of developer documentation. Docs should be...
If we fail to meet any one of these goals sufficiently, it's reasonable to assume that our docs will go unused. Docs that go unused fall behind, wither and die quite quickly. Whatever solution we converge on should meet all 4 of these in order to be successful.
One litmus test we could use to determine if we're meeting these goals: are engineers on the Kibana team actually finding these useful?
Context
Broadly speaking, there appears to be 3 types of documentation that we have or need for Kibana:
This proposal addresses (2) and (3) and does not propose any substantial changes to (1).
Plugin developer documentation
These docs should aid both internal and external developers in building full-fledged Kibana plugins, covering both the APIs and tools available, as well as best practices and cookbooks.
Kibana contributor documentation
These mostly serve to augment the plugin developer docs with information about contributing to our repository directly:
Where should dev docs live?
TL;DR: We should invest time into getting our docs to work with the existing elastic/docs system in order to publish on elastic.co/guide as a Asciidoc "book" separate from our user guides.
Beats has separated their docs into the reference guide and the developer guide and I believe we should do the same.
At a high level, I propose we:
The advantages of this approach:
Custom tooling
In order to make this dream a reality, we will need to invest in some custom tooling, though I don't expect it to be much.
TSDocs will need to be extracted and output to Asciidoc. While there is no existing output in the open source community, Microsoft's API Extractor tool provides examples and code we can use to do this. A rough glance at the source code points to this not being a large effort. Building our own tooling gives us a full control on the format and output of what we want these docs to look like. We should be able leverage the features of Asciidoc to make these generated docs as interactive and cross-linked similar to other tools.
We are also exploring adding OpenAPI specs to public RESTful APIs. If we adopt this, then there is already existing tooling in the community for generating Asciidoc for these specs. If needed, we could also fork this to gain more control. This is something the Elasticsearch team could leverage as well as they move to OpenAPI.
Freshness
One complaint about using the existing Asciidoc system is that dev docs are likely to get out of date quickly because developers forget to update the corresponding documentation files when updating code. I think there are 3 things we can do to fix this:
docs/
file tree into the book. For example, a high-level asciidoc file describing a plugin in the source code should be usable in the external documentation book.Richer outputs
Many of the tools we're using (or planning to use) have rich documentation outputs (eg. OpenAPI) which we should leverage if they offer real benefits or features that we cannot implement or add easily to the existing Asciidoc system.
I don't have a grand plan here, but I don't see why we couldn't generate these outputs and link to them from the Asciidoc book, all as part of the regular elastic/docs pipeline.
I think this is something we explore in the future one we're in a good place with our existing docs. The reality is that we have a lot of work to do just to make ANY dev docs actually exist and usable. The lack of docs is a glaring hole in both our internal onboarding and external plugin dev community. Making any docs exist is more important than how rich the interface is.
Miscellaneous
Points for discussion
The text was updated successfully, but these errors were encountered: