Documentation Reorg: How-to and reference guides #3869
Comments
|
Hi @philippjfr . I love how-to guides. I was thinking that your how-to titles are technical and solutions. Users might not know they should be interested in So I was thinking the the titles should be more like How to solve problem X using the solution Y. So for example instead of how to use Looking at the Diataxis frameworks description of Howto also makes it clear that they provide solutions to user problems. And they mention recipes: When you search for recipes you search for the what (pan cakes) not the how (use a pan).
So for example the Howtos on APIs could be APIsHow to quickly explore your data interactively by using (I would remove A primer on using Param. as its a tutorial). |
|
Excellent points @MarcSkovMadsen, I agree with everything you said. |
|
An idea could be to let 5 of us write one how to each. We would probably get 5 different ways of doing that. From that try to discuss, align and agree on how our how to should be. In that way we would have 5 persons that feel ownership of how tos. And writing one how to should not be that big an effort :-) They should be adressing one problem, short and to the point similarly to a recipe. |
|
And there is a reward at the end of the tunnel
|
|
For me how-to should take a lot of the look and feel of blog posts. They feel modern and fun. They solve a specific problem. The most useful blog posts are easiy to follow and can easily be transformed (copy pasted or downloaded) into a starting point |
|
Two examples to the How to list
|
|
The new pyodide powered documentation is awesome. Everybody would like to be able to do that. I think we should add a how-to guide on that
|
This is a improvement on the titles but given their wide scope (especially of the first - 'exploring data') and that APIs is probably the most important aspect of the documentation, I think we should still be careful about not having the content veer into mish-mash territory. Maybe writing an |
|
A lot of inspiration for valuable topics for How-to guides can also be found in the posts on Discourse. |
|
Just to say that I've decided to merge my PR starting the migration from user guides to how-to guides. Overall I'm quite happy with the way this has gone however I almost certainly carried over a bunch of material that is not in the "recipe" style so there will be a process in cleaning that up. There are also still a few user guides left over that have not been migrated anywhere. However overall I'm confident that this is a big improvement and the remaining material can be migrated into reference and background material. The next step here is that @droumis will report back and suggest what to do with the remaining material. Existing User GuidesExisting user guides were grouped Core
Reference
State, Caching & Callbacks
Export
Server usageMigrated cleanly to server configuration, server integrations, deployment and authentication how to guides. Sections
|
|
This is what I was drafting to comment in #4251, but it got merged already, so I'll leave the comment here: In general, to rein in this massive PR a bit (referring to #4251), I would err on the side of getting the new structure in place, and then continue wordsmithing in future and more contained PRs. That said, you requested that I focus on what to do with certain user guide pages, so I will use one of them - Components - as a concrete example of how I’m thinking about this migration to a Diataxis-like architecture. Once we align on the approach, I will start helping to act on it. 1. The Components User Guide, as currently written, can essentially be used to initialize a Components page in the Background section. It is primarily a discussion about the concept of components and types of components, such as that they are built on the Param library and the distinguishing aspects of the different component types - Pane, Widget, and Panel (Row, Column, Tabs, GridSpec). The bulk of this content is understanding-oriented, which is most useful for the users in a learning phase rather than those in midst of working. Later on, further content can expand this proposed Components Background page, such as with design decision reasoning, technical constraints, or analogies/connections to other external/internal things. 2. Consider cherrypicking any crucial/core concepts that every new user should know and incorporate them into the Getting Started - Core Concepts page. The Core Concepts page currently contains some information about components; mainly in the ‘Display and Rendering’ and ‘Widgets’ subsections. While these sections of the Core Concepts page can be improved on clarity, I don’t yet see any obviously missing crucial concepts that could be derived from the Components User Guide page. Perhaps one candidate missing topic is the explicit linking of components, as an example of using .jslink is in the current Components page. But honestly, I don’t think that .jslink qualifies as a core concept. If you want something about explicit component linking in the Core Concepts, it should probably be .link which would come when parsing/migrating the Linking User Guide, so no action on this is needed now. I think the only addition to be made to the Core Concepts presently is a link to the Components page within the appropriate context. For instance, after the ‘explicit’ construction of pane type is mentioned in the Core Concepts page, I would add a mention/link to the ‘Panes’ section of the Components page. 3. Identify any useful ‘how to …’ questions that this page addresses. As a reminder, some characteristics of a Diataxis How-To page include having a specific scope, describing the problem, excluding discussion, including a sequence of actions, and following a consistent format. With that in mind, some simple candidate How-To pages that the Components User Guide could address include: how to load the Panel extension in a notebook, how to construct a pane, how to view pane type, how to access widget values, how to add widget and pane components to a panel, how to add a title to a tab panel, how to set a GridSpec panel to have responsive or fixed sizing, how to place an object at a specific location in a GridSpec panel. 4. I don’t immediately see how any of the Component User Guide might fit within a reference section. In general, the Reference Gallery and Reference API are still confusing sections to me and I think they should be handled outside of this PR. Perhaps, some simple examples from the Components page could be used within a reference, but these seem to already be covered. |
|
Just noting that I spoke to @philippjfr and he agreed with my approach outlined above. |
|
Closing, the how-to guide will always be evolving but @droumis and I made great progress here. |
We are currently in the process of reorganizing our documentation and one of the central themes is to separate explanations, how-to guides and reference material. Our current user guides are a total mish-mash of all of these and it's quite awkward to find what you want. So my first goal is to come up with a list of How-to guides, additional reference guides and sections on where to put them. Please chime in with additional suggestions.
How To Guides
APIs
pn.bind?pn.depends?interact?Customization & Layout
Templates
Editors and notebooks
Advanced features
Server deployment
Reference Guides
panel servepn.servepn.bindpn.configpn.stateThe text was updated successfully, but these errors were encountered: