Categorise a subset of JupyterHub's web pages into the Diataxis framework

[sgibson91]

We would like to transform our documentation to follow the diataxis framework. This microtask will begin the mapping process of our current docs onto the framework.

Many Outreachy applicants can work on this issue at the same time.

1. Familiarise yourself with the diataxis framework. There's a YouTube video if you prefer to listen: https://www.youtube.com/watch?v=t4vKPhjcMZg
2. Select a high-level documentation section from the JupyterHub website (https://jupyterhub.readthedocs.io/en/stable/), e.g. Administrator's Guide
3. For each sub-section, map where on the four quadrants of the diataxis framework each page of the documentation sits. You can use any software you like for this, for example, Miro. Or even just a pen and paper!
4. Upload a screenshot / link / photograph of your mapping as a comment on the issue and tell us a little bit about what you learned using the following questions as prompts (A couple of sentences is fine! We are not expecting an essay for this 🙂 ): a. What does the mapping tell you about the current state of our documentation? b. Where would you create more documentation to help a user or a developer? c. Could the present documentation be redistributed more evenly across the quadrants? How so? d. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

Update

This microtask will be closed to new applicants on Monday 24th October (end of day UK time).

Please make sure your contributions are recorded and begin your final application on the Outreachy website. If your issue/PR is still open when we close this project, it will still count as a contribution. Closing the project will not affect your ability to record contributions and make your final applications.

[welcome[bot]]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively. You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! :wave:
Welcome to the Jupyter community! :tada:

[Annosha]

Hi @sgibson91 I want to go ahead with Administrator's Guide and categorize into respective diataxis framework. Once done I'll post it here in the comments section. Thank you.

[zeelyha]

Hi @sgibson91. I want to get started on the API Reference sub-section. I will keep you updated on my progress. Thank you.

[AdrianaHelga]

Hi @sgibson91. I want to work on Getting Started sub-section. I shall post it here once I've completed. Thank you!

[zeelyha]

@sgibson91 When answering the questions you listed, does 'documentation' refer to the entire documentation or just the section we're working on?

[M0Hassan]

Hi @sgibson91, I would like to proceed with the Installation Guide sub-section. I will post my findings here once I finish. Regards.

[Annosha]

@sgibson91 here is the link to miro categorizing contents of this page into diataxis framework.

Brief Summary:

Troubleshooting: Overall this section lacks the format of How to Guides i.e. answering the questions in steps. Additionally, it needs to be more concrete i.e certain topics can be rewritten e.g. Errors these can be rewritten in the form of questions and answers. Also, IMO troubleshooting commands must go on top in the troubleshooting category, etc.

Upgrading JupyterHub: Some topics here are more suitable to be put under Explanations.

While going through Administrator's Guide category, I observed the content is scattered, and mixed up, and in some places unnecessary explanations are provided (which can go under the Explanations category explicitly). A lot must be done to make it precise and easy to navigate.

[Hauwarh]

Hi @sgibson91 My name is Hauwa an outreachy applicant. I would like to get started with the contributing page.

[Hauwarh]

@sgibson91 When answering the questions you listed, does 'documentation' refer to the entire documentation or just the section we're working on?

I think @sgibson91 is referring to the particular section you choose to work on.

[zeelyha]

@sgibson91 When answering the questions you listed, does 'documentation' refer to the entire documentation or just the section we're working on?

I think @sgibson91 is referring to the particular section you choose to work on.

Alright, Thank you Hauwarh

[zeelyha]

@sgibson91 Here is the link to the Miro board mapping the contents of the API Reference subsection using the Diataxis framework.

Observations and Suggestions: From the mapping, it is clear that there is uniformity in this section in terms of categorization. Each page gives a technical description of the machinery as expected. I would add an example of command usage in the Users subsection to give readers and developers a better understanding of its context. I don’t think the present documentation could be redistributed more evenly as every page describes the architecture of the software. I didn’t find a particular page that could be improved, although I noticed a few inconsistencies in language and terminology e.g. (oauth & OAuth), (Hub, the Hub & the hub). To improve this I would suggest initially stating the difference in these terms if there are any, or making sure only one of these terms are used across board.

Thank you.

[falyne]

Hi @sgibson91 This is a screenshot of the miro board mapping of the Administrator's Guide using the Diaxtaris framework

The documentation is divided into documentation quadrant but not properly outlined and separated. Some sub sections have a mix of various documentation quadrant.
-The document outline does not clearly separates parts at a glance To help a user or a developer, I would create a reference sub section that will give clear directions on some of the available resources and their links

Yes this document could be redistributed more evenly Firstly we need to clearly outline each quadrant on the website at a glance moving on, the sub sections under upgrading jupyterHub -Upgrade JupyterHub packages -SQLite database disadvantages -What happens if I delete my database? Has a lot of explanations in it, Those discussions could be moved from there to the explanation quadrant and then statements with more specific commands be left there. Also, at the troubleshooting section, the how to guides can be better framed in a question format to allow users clearly understand if the section and have a sense of direction. -I think the Reference guide need to be improved technically

[M0Hassan]

Hi @sgibson91, here is the link to the Miro board where i have mapped the Installation section using the Diataxis framework.

Observations and Suggestions

From the mapping, I have gathered that there is largely a balance in regards with the placement of the sub-sections within the diataxis framework.

The Using Docker subsection requires more documentation. I have mapped the Using Docker subsection to the How-to guides quadrant. I think that this page can be improved by providing readers and developers clear directions. Currently this page is a bit too wordy with no visual contrast. I would suggest that it be divided into smaller sections with headings and sub-headings that correspond to the issue being addressed. A reader should get an overview of the content on first glance.

I do not see the need for redistribution in the installation section. I think there is an even balance across the pages.

The installation section does not have a reference page. This can be added to further improve the documentation. It should clearly indicate the software components that are central to the installation process and how to use them.

[ArafatAbdussalam]

Hello @sgibson91 I

Is the mapping of the sub-sections based on the current documentation or the proposed solution to the documentation? If so, the subsections of the Installation section fall under different frameworks which unless the contents are being restructured by adding or removing can be re-grouped.

My proposed idea is that the documentation page needs to have a table of content containing the four quadrants, hence other subsections can be recategorised.

Question: What does the mapping tell you about the current state of our documentation?

Answer: Having gone through the JupyterHub documentation, I realized that the contents are not properly structured using the Diataxis Framework. I will like to improve the structure of the "Installation" section.

Question: Where would you create more documentation to help a user or a developer?

Answer: I want to improve the Installation section

Question: Could the present documentation be redistributed more evenly across the quadrants? How so?

Answer: Yes. By re-categorizing the "Installation" section and adding more subsections like Overview, How to Install, and providing links to reference guides on how to install the PAM. In my opinion, the "Get Started" section could be changed to "How-to Guides", that way other frameworks can be regrouped.

Question: Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

Answer: The Quickstart subsection has a child subsection titled "Installation" and that is under its parent section titled "Installation", as a new user I found it difficult to comprehend the installation guide. More so, the "Installation Basics" had a warning that JupyterHub doesn't run on windows, I think the warning should have been provided in the "Prerequisite" subsection.

[Temidayo32]

My answers to this question are based on the section I reviewed: Technical reference

https://miro.com/welcomeonboard/eXdHR25jeDB1TUVOd2pwTWx5OUczU2Q3enRSdTRoMnVHdDdiUENqdmx6dUIxREtzRjlleVhwYVVoMmtNUTVKN3wzNDU4NzY0NTM1NTQ2NTU3NjA3fDI=?share_link_id=636780039084

Here is the link to check my work on Miro

a. What does the mapping tell you about the current state of our documentation?

First, bringing the documentation to align with the diataxis framework would require a major revamp of the entire documentation. Whole documentation would need to be cut out from their current sections into new sections matching the diataxis quadrants; and whole documentation would need to be re-written to fit into a specific quadrant, and the snippets of other quadrants in the documentation would be cut out, and can then be expanded into their own separate documentation if need be, or discarded.

b. Where would you create more documentation to help a user or a developer?

How-to guides are problem-oriented. I would create more how-to guides to help users/developers unblock themselves easily in using the different part of the Jupyterhub machinery. I particularly had suffered due to the shortage of them. There were instances I had specific problems, for example, "how to create a JupyterHub configuration file", and there was no documentation on how to do just that! It was annoying until I figured it out on my own.

c. Could the present documentation be redistributed more evenly across the quadrants? How so?

Absolutely. The current documentation does more of explanation and contains very little of how-to guides. More often than not, especially based on the section (Technical reference) I reviewed, how-to guides are added as snippet between large blocks of explanation content, or they are reduced to few lines of directions that are not enough. These how-tos can be removed and expanded into full how-to guides. Also, tutorials are best fit for first-time users of Jupyterhub. They should populate the get started/installation section. The reference guides also are buried in other documentation content, which shouldn't be so. They should be easily accessible. I think using the diataxis frawework should address this issue.

d. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

Link: https://jupyterhub.readthedocs.io/en/stable/reference/config-reference.html

Yeah, I found this documentation that should be moved to a place where it can be easily found. It is buried too deep in the documentation given the significance of using and generating configuration in Jupyterhub. Secondly, it should appropriately be an how-to guide and should be written to match the how-to format with steps.

[AdrianaHelga]

Hello @sgibson91. Here is a link to the diataxis framework for Getting Started subsection of the documentation. My Findings: Since the majority of this documentation subsection explains how to start using JupyterHub, it would be good to restructure each part into a How to Guide and list the steps in a more concise manner. Under Security settings, the explanation of cookies can be put under discussions as it understanding oriented rather than problem oriented. On Authentication and User basics, the Use OAuthenticator can include links to how get started with each directly rather than having to go to the github page to find the link to the instructions.

General Comments

• The documentation is currently not structured using the diataxis framework.
• I would write more documentation for FAQs, covering the questions that have been asked most on sites such as StackOverflow. Only one question has currently been answered on this section.
• It is possible to redistribute the documentation more evenly. Having the Getting Started subsection on the how to guides would be a great start.
• Most pages on the getting started sub-section, such as External services can be improved to list the contents in a series of steps, rather than just listing them in prose.

[sgibson91]

So many amazing contributions so far! <3

[Temidayo32]

@sgibson91 what do you mean by "<3"?

[sgibson91]

what do you mean by "<3"?

Sorry, it is a symbolic representation of a heart indicating that I love all the great work that has been happening in this thread! I mistakenly thought that GitHub would transform it into the emoji version: ❤️

[Jaykold]

Hi @sgibson91, here is a Link to Miro showing my categorization for Administrator's guide using the Diataxis framework.

a. From my mapping, the documentation is not suitably structured to follow the Diataxis framework. There is a mix of both Tutorial and How-to guides in both Upgrading JupyterHub and Troubleshooting; b. I would create more documentation for Interpreting common log messages as Explanations are limited on this page; c. Yes, I believe it could. There are some topics in Troubleshooting and Upgrading JupyterHub that I think are more suited to other quadrants like Explanations d. The Administrator's Guide can be improved in its arrangement to follow the Diataxis framework; Upgrading JupyterHub and Changelog: There seem to be inconsistencies in terminology such as OAuth and oauth. There is no definition to distinguish these terms if they differ or are the same. This might confuse the user/reader; Troubleshooting: There are some topics I think should come before others on this page and some topics I think are redundant and should be removed from this page so as not to bore the reader/user.

[Temidayo32]

what do you mean by "<3"?

Sorry, it is a symbolic representation of a heart indicating that I love all the great work that has been happening in this thread! I mistakenly thought that GitHub would transform it into the emoji version: ❤️

Oh, okay . Thank you @sgibson91 ❤️

[Joel-Ando]

So many amazing contributions so far! <3

Hi! Mrs sgibson91 i hope projects will not be close for further contribution. some of us are still behind... haha!!

[sgibson91]

No, not yet :)

[Joel-Ando]

Mrs sgibson91 for setting up the environment to run jupyterhub documentation can we use other linux distros or only ubuntu.?

[sgibson91]

@Joel-Ando You do not need a local instance of JupyterHub running to contribute to this issue since it is focussed on the documentation

[Christiandike]

The attached photograph contains diataxis framework mapping for the Technical Reference section.

Answers to the Questions

a. What does the mapping tell you about the current state of the documentation?

The current state of the documentation (Technical Reference section) is highly information-oriented because a significant amount of the material focuses on describing the product's specifications and no more.

b. Where would you create more documentation to help a user or developer?

I would rather build on the current documentation in these ways:

• Revise documentation that overlaps between multiple quadrants and restrict to one appropriate quadrant
• Suggest a dedicated "Tutorials & Guides" section in addition to current sections, to house all guides/tutorial-based documentation in one place and allow for easy navigation
• Revise guides and tutorials to employ a more concise, heavily-bulleted step-by-step format

c. Could the present documentation be redistributed more evenly across the quadrants? How so?

Some documentation overlaps across multiple quadrants. By identifying them and modifying them to fit into their appropriate quadrants, it is possible to achieve a more even distribution of documentation across all quadrants.

d. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

The title of this documentation can be appropriately renamed to serve as a how-to-guide.

Suggestion: How to configure Github OAuth for JupyterHub Deployment

Also, the documentation's structure can be revised to follow a precise, step-by-step format.

[Joel-Ando]

@Joel-Ando You do not need a local instance of JupyterHub running to contribute to this issue since it is focussed on the documentation

thanks you.

[Jaykold]

Hi @sgibson91, here is my Link to Miro showing my categorization for RBAC Reference using the Diataxis framework.

a. The documentation is pretty much well structured but can be improved; b. I would add more documentation to the JupyterHub RBAC page; c. Yes, I believe they can. Some documentation is situated in the wrong quadrants; d. The JupyterHub RBAC page is a bit circuitous in its wording, I would change some of the wording to avoid obscurity so as to keep it simple and easy to understand.

This documentation is as good as complete but not finished!

[melissakirabo]

The Contribution Section

a. What does the mapping tell you about the current state of our documentation? It mostly consists of How-to-Guides, therefore, it is a predominantly task oriented section. The How-to-Guides clearly state the prerequisites needed in each section, which mitigates the possibilities of getting errors during the installation process.

b. Where would you create more documentation to help a user or a developer? Some sections require updating and/or adding to the number of examples such as the Troubleshooting section under Setting up Development Install and Troubleshooting Test Failures under the Testing JupyterHub and Linting Code section

c. Could the present documentation be redistributed more evenly across the quadrants? How so?

1. Yes, there is a need to clearly section the documentation into the different quadrants right from the landing page such that the user knows exactly what to expect.
2. There were no tutorials in the Contributing Section and it was predominantly based on How-to-Guides.
3. Some sections of this documentation will require reorganization according to the Diataxis for example the Testing JupyterHub and linting code which has both How-to-Guides and Reference.

d. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

1. Reporting security issues in Jupyter or JupyterHub – I think that this page could use a high level summary of what a “security issue” is such that the reader has an idea. Whilst a link to the Security overview has been attached, the reader still has no idea of what the security issue is beforehand.
2. Troubleshooting section under Setting up Development Install and Troubleshooting Test Failures under the Testing JupyterHub and Linting Code section. Both subsections lack a substantial number of examples for a developer, therefore, examples of possible errors should be added, as well as how-to-guides on what to do to clear the various errors.

[Achele]

Hi @sgibson91 , here is my Link to Miro showing my categorization for Administratio's guide section using the Diataxis framework.

Summarily, the mapping shows that the administration's guide section though divided into the different documentation mode, does not have a clear distinction amongst them, as some subsections had more than one mode of documentation which were unnecessary. For instance, the upgrade JupyterHub packages, SQLite database disadvantages and what happens if i delete my database? subsections had lots of explanations in them. I would take those out into an explanations section and leave only the one's with a more direct approach.

In addition, at the troubleshooting section, the how to guides does not align with its format of documentation. it should be more of a question prompt such that the users can clearly understand and use adequately. Also, the reference section should have a sub section for any available resources and links.

[victorvictoria-maker]

Hello, team and mentors - @sgibson91, @minrk and @GeorgianaElena. Here is the LINK to miro showing my grouping of the Installation, Get started and Technical subset of Jupyter's documentation using Diataxis framework.

Answers to questions

1. What does the mapping tell you about the current state of our documentation? The current state of the documentation can be improved by sectioning all the contents of the documentation into 4 quadrants according to the Diataxis framework (Tutorials, How-To-Guides, Discussions and References). This can give the users a focused direction on whatever information or guidance they need.

2. Where would you create more documentation to help a user or a developer? I would rather work on the current documentation - group all content into the 4 quadrants, ensure one part of the documentation leads to the next - a step-by-step format, reduce redundancy and ensure quadrats do not overlap. Also, I would work on creating more Discussions aspect so as to clarify and illuminate particular topics for users. For instance, the pros and cons of using JupyterHub OAuth or of google auth.

3. Could the present documentation be redistributed more evenly across the quadrants? How so? Yes, they can be redistributed. Parts of the documentation that overlaps with quadrants can be modified. Also, parts of the documentation that does not seem to fit into any of the quadrants can also be worked on.

4. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it? The administrator's guide can be improved especially the troubleshooting section.

[luquiceno]

Hi @sgibson91 here is my screenshot for the section API Reference using the systematic Diataxis framework.

A. What does the mapping tell you about the current state of our documentation? Analyzing the current state of the documentation, I find that some adjustments could be made it. But in general I find the documentation well structured, so that a user can go to what is looking for without having to get lost in so much documentation.

B. Where would you create more documentation to help a user or a developer? When a user or developer enters to each Sub-section such as "Services", an initial paragraph could be added with a brief description or explanation of what for example "Services" means or implies in/for Jupyterhub. And if possible add an example either including a link or describing it directly on the page.

C. Could the present documentation be redistributed more evenly across the quadrants? How so? For the API Reference section that was analyzed, I would not distribute it in the quadrants. Since the information described there is more technically oriented, mentioning classes, methods etc. But if we take all the Jupyterhub documentation, it can clearly be distributed through the quadrants.

C. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it? From the revised section, I would include in all API Reference Sub-sections what I described as an improvement in question b). In addition I would make some adjustments to visually improve the distribution of the information. For example using more ordered list <ol></ol> or unordered list <ul></ul>.

[EstherChristopher]

We would like to transform our documentation to follow the diataxis framework. This microtask will begin the mapping process of our current docs onto the framework.

Many Outreachy applicants can work on this issue at the same time.

1. Familiarise yourself with the diataxis framework. There's a YouTube video if you prefer to listen: https://www.youtube.com/watch?v=t4vKPhjcMZg
2. Select a high-level documentation section from the JupyterHub website (https://jupyterhub.readthedocs.io/en/stable/), e.g. Administrator's Guide
3. For each sub-section, map where on the four quadrants of the diataxis framework each page of the documentation sits. You can use any software you like for this, for example, Miro. Or even just a pen and paper!
4. Upload a screenshot / link / photograph of your mapping as a comment on the issue and tell us a little bit about what you learned using the following questions as prompts (A couple of sentences is fine! We are not expecting an essay for this 🙂 ): a. What does the mapping tell you about the current state of our documentation? b. Where would you create more documentation to help a user or a developer? c. Could the present documentation be redistributed more evenly across the quadrants? How so? d. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

Hello @sgibson91 I'd be working on the API reference subsection. I'm currently reading through it to see how it can be organized into the necessary documentation type. I'll drop my opinion on the current state of the API reference documentation and then go ahead to restructure it if need be.

[sgibson91]

... and then go ahead to restructure it if need be.

@EstherChristopher No need to restructure right now! That will be a task for the intern we take on

[Suldana]

Hello @sgibson91 I transform the documentation to follow the diataxis framework, Here is the screenshot of Contribution secssion.

1. What does the mapping tell you about the current state of our documentation? We discover how simple it is for a person to comprehend and locate a manual to complete tasks quickly. It is mostly task-oriented because it comprises primarily of How-to-Guides.
2. Where would you create more documentation to help a user or a developer? I will create more documentation under Testing JupyterHub and listing code and all of its session (Test organization and code formatting and listing) also Reporting security issues in Jupyter or JupyterHub. Which is very helpful for users
3. Could the present documentation be redistributed more evenly across the quadrants? How so? The documentation needs to be clearly divided into the several quadrants. It is not a method of action more places were needed to have a tutorial like Reporting security issues in Jupyter or JupyterHub
4. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it? Some of the installation that was required wasn't explained in detail or even had a clear purpose. Making the documentation more user-friendly for those who are using it for the first time is something I would like to do.

[EstherChristopher]

@sgibson91 Ok, thank you for the clarification.

[EstherChristopher]

Here is the image URL to the mapping of the API Reference using Diataxis framework: 3280BBB8-7975-4B28-8B3F-B7F3959E5C38

### JupyterHub API reference

a. What does the mapping tell you about the current state of our documentation?

The overall documentation of the Jupyter API is quite orderly. It is largely a reference information type. However, some adjustments can be made to make the documentation even better.

b. Where would you create more documentation to help a user or a developer?

The “Authenticators” subsection and “Services” subsection seemed to want to divulge more information but were restricted by the Diataxis framework which requires that each piece of information sticks to its type in the quadrant. In my suggestion, these 2 subsections, in particular, deserve to also be given an in-depth description in the explanation type of information. Part of the “Services authentication” can also have more documentation made into “tutorial” information.

c. Could the present documentation be redistributed more evenly across the quadrants? How so?

In my opinion, more documentation needs to be created around the ‘Authenticators” sub-section. The information here should be placed in the “explanation” quadrant and be more explanatory than it currently is. Same as the “Services” sub-section. The “Services authentication” should also have some of its parts made into “tutorial” information. If possible, each sub-section should have pieces of information that are distributed among all quadrants for a clearer understanding for the users and clarity on the part of the technical writer. Each piece of information should take its own place distinctly.

d. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

Certain parts of “Services authentication” should be made into “tutorial” information and the remaining parts “reference” information. They should be made distinct from each other for more clarity. The “Authenticator” sub-section could generally have an “explanation” and “tutorial” information. Notwithstanding, the overall API reference documentation has a good standing.

[Mackenzie-OO7]

Here is a link to the mapping of the Get Started section according to the Diataxis Framework

1. What does the mapping tell you about the current state of our documentation?

   • The mapping tells me that the current documentation does not have enough tutorials, and is not explicit enough for a new user.

2. Where would you create more documentation to help a user or a developer?

   • I would create more documentation in tutorials.

3. Could the present documentation be redistributed more evenly across the quadrants? How so?

   • Yes, it can. The sub-sections should be structured properly, in such a way that the characteristics of one quadrant of the Diataxis framework does not appear in another.

4. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

   • The Configuration Basics page should should be a tutorial. It is a crucial step because, for a new user, it determines if they are going to continue with their learning or not, and for a developer, it determines if they can perform the work they set out to do. It not have references providing additional details, as those can be distractions. It should give the user a single path to follow and what to expect. It also mentions terms like "spawners", "authenticators" etc, which a new user might not be familiar with, whereas it should only mention known terms, defined tools, materials, processes and conditions that have been carefully set before the learner.
   • The Frequently Asked Questions page does not have enough questions answered
   • In the Networking Basics page, the titles should start with "How to". For example, "How to set the Proxy’s IP address and port"
   • At the beginning Authentication and User Basics page, there should be a list of the actions the page teaches the user to perform, like in the Networking Basics page.

[Joel-Ando]

Hi Mrs @sgibson91, As instructed above, here is the mapping miro screenshot of the JupyterHub RBAC using the Diataxis Framework.

1) What does the mapping tell you about the current state of our documentation? -The current state of the document indicate uneven distribution since some quadrants has little or no processes or task. For instance the Tutorial, the How-To Guides, and the Reference.

2) Where would you create more documentation to help a user or a developer? -I would create more documentation in How-To Guides. This is to ensure that both user and developers follow the right procedure to accomplish their expectations.

3) Could the present documentation be redistributed more evenly across the quadrants? How so? Absolutely. By taking the Technical implementation sub-section from the Explanation Quadrant to the How-To Guides Quadrant. 4) Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it? Yes. I think improving the Technical implementation page will be a necessity by elaborating more in a step-by-step manner rather than explanation.

Thank you JupyterHub team.

[Beamps-code]

Hi, my name is Bimpe, an outreachy applicant, I am super pumped to be contributing to this project.

[Beamps-code]

Hi @sgibson91 This is the LINK to my Miro Board 1) What does the mapping tell you about the current state of our documentation

After using the Diataxis framework to analyze the documentation of the “Get started section”, my inference is as follows, there are no tutorials to help new users get familiar, but rather “How-To Guides” for users who already have basic competency. Also, there are not enough references for users to quickly consult for an in-depth technical description of the product.

2)Where will I create more documentation to help users or developers?

I will create more documentation in both tutorials and references, to help new users achieve basic competency and provide quick consultations about the product for everyone.

3)Could the present documentation be redistributed more evenly across the quadrants? How so?

No, it is adequately distributed among the 4 quadrants, it is the Getting Started section, and because of this, most of the documentation fell under the “How-To Guides”.

4) Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

Yes, I will improve on the following pages; Configuration Basics, Frequently asked questions and Institutional FAQ, Security settings, and Authentication and User Basics

Configuration settings: The configuration basics document is useful if the user is already familiar with technical terms already, but if that is not the case, it will be challenging for new users to complete the tasks, I will create a 3-minute tutorial to help new users get started.

Frequently asked questions and Institutional FAQ: I will make institutional FAQ a subset of “Frequently asked questions” to limit confusion among users because, they might know the difference between the two, and they might be looking for answers in the place.

Security settings and Authentication and User Basics: The language used to depict warnings or notices should be consistent for all documentation, the use of different colors brings about disorganization in the document structure, I will use one color for warnings and notices in all the sub-sections.

[alwasega]

We would like to transform our documentation to follow the diataxis framework. This microtask will begin the mapping process of our current docs onto the framework.

Many Outreachy applicants can work on this issue at the same time.

1. Familiarise yourself with the diataxis framework. There's a YouTube video if you prefer to listen: https://www.youtube.com/watch?v=t4vKPhjcMZg
2. Select a high-level documentation section from the JupyterHub website (https://jupyterhub.readthedocs.io/en/stable/), e.g. Administrator's Guide
3. For each sub-section, map where on the four quadrants of the diataxis framework each page of the documentation sits. You can use any software you like for this, for example, Miro. Or even just a pen and paper!
4. Upload a screenshot / link / photograph of your mapping as a comment on the issue and tell us a little bit about what you learned using the following questions as prompts (A couple of sentences is fine! We are not expecting an essay for this slightly_smiling_face ): a. What does the mapping tell you about the current state of our documentation? b. Where would you create more documentation to help a user or a developer? c. Could the present documentation be redistributed more evenly across the quadrants? How so? d. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it?

Hello @sgibson91 , Here is a link to a Google Sheets Doc of how I would map the Technical Reference documentation using the Diataxis Framework.

Additionally, below are my responses to the four questions: What does the mapping tell you about the current state of our documentation? Overall, the present documentation provides a good starting point for someone who seeks to work with JupyterHub. However, what I observed was that there is a general need to restructure some documents to make them more clear, to regroup related documents together, and to title some appropriately as per their contents. For instance, the mapped pages are presently grouped under the heading Technical Reference, which is somehow misleading as there are tutorials, explanations, and how-to guides within this broad heading.

Where would you create more documentation to help a user or a developer? I especially found References to be lacking in this section of the documentation. According to the Diataxis framework, References in a software system should describe the software, its components, and how to use them. However, in this case, I could only find three such articles, which, therefore, leaves a beginner user with a lot of extra homework to look for articles or responses on the Internet regarding what JupyterHub is and how to utilize it effectively.

Could the present documentation be redistributed more evenly across the quadrants? How so? Yes, the present documentation can be spread more evenly. One way of achieving this objective is by re-titling some of the present articles. For example, some of the documentation that presently read and are titled as Tutorials are actually References or Explanations. A case in point being Eventlogging and Telemetry, which I have grouped as a Tutorial due to how it is worded but can actually be an Explanation as it should be explaining how JupyterHub achieves the logging of events. Alternatively, it can be converted into a How-To Guide if given the proper title and restructured. The documentation can also be redistributed more evenly by preparing separate How-To Guides to complement the Tutorials. For instance, Using JupyterHub's REST API can be made into a How-To Guide if given a specific use-case such as Using JupyterHub's REST API to authenticate services.

Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it? Yes, I found instances of pages that need improvement or changes. For instance, the Configuration examples page is incomplete and should, therefore, be reworked with the appropriate examples as captured in the document's title. Additionally, the JupyterHub REST API page simply gives the API specificication without a description of what the reader is looking at. As such, a brief description at the top of the page and how the reader can interact with the given endpoints would make for a better article.

[Dev-Liz]

a. This mapping shows that the Getting started section of the documentation is already structured to follow the Diataxis framework, as it includes TUTORIALS, HOW-TO-GUIDES, EXPLANATIONS, AND REFERENCES, all distinct and equally separated on different pages.

b. For a user or a developer who already knows how JupyterHub works, I would create more documentation on the HOW-TO-GUIDES section.

c. No. The present documentation is already evenly distributed on the GETTING STARTED pages, with every element of the Diataxis framework taking 2 pages each, of the documentation 8 total pages.

d. Yes.

• Images illustrating each step, could be added to the TUTORIAL and part of the HOW-TO-GUIDES sections of the documentation, to aid easy understanding.
• Pages on the EXPLANATION section, can be improved with analogies.
• Pages on the REFERENCE section, can have a better-structured layout, to improve readability.

[EstherChristopher]

Here is the image URL to the mapping of the Contributing documentation using the Diataxis framework:

FAAC7A9C-29C2-47ED-BAF2-38903877B095

Contributing documentation of JupyterHub using the Diátaxis framework

a. What does the mapping tell you about the current state of our documentation? Probably due to the nature of this documentation which is a contributing documentation, some of the information does not seem to best fit into some of the Diátaxis quadrants they are currently in. Certain information is not fit for the quadrant they are in.

b. Where would you create more documentation to help a user or a developer? The "contributing documentation" sub-section deserves to have more documentation meant for "explanation" information. It is in the "how-to" quadrant but has information littered in it that could be more explanatory and made into an "explanation" information.

c. Could the present documentation be redistributed more evenly across the quadrants? How so? The "Testing JupyterHub and linting code" sub-section does not specifically fall into any of the Diátaxis quadrant even though for the sake of the mapping I placed it in the "how-to" quadrant. I was uncertain if to place it in the tutorial or how-to section and this is because it has information surrounding both. There is also information meant for "reference" in this sub-section. My recommendation would be to separately branch certain information in this sub-section into a "tutorial" and "reference" quadrant.

d. Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it? Yes, please. "contributing documentation" sub-section should be made to have both a "how-to" and "explanation" sub-section to thoroughly communicate the information. The "Testing JupyterHub and linting code" sub-section should be made to separately have a "how-to", "tutorial", and "reference" information quadrant.

[QNNAKWUE]

Hello @sgibson91, here's a screenshot of my mapping on the issue and a little bit about what I learned. Looking forward to your review. Thank you.

What does the mapping tell you about the current state of our documentation? The mapping underscores the importance of structure in our documentation. It helps us see from a broader spectrum the lack of structure in our current documentation and the dissatisfaction our users might feel as they interact with our products. With the diataxis framework, we are now aware that our documentation is lacking clarity, and straightforwardness, not only for our users but also for our contributors.

Where would you create more documentation to help a user or a developer? I’ll create more documentation in the “Get started” sub-section to help a user or a developer. After reading the documentation, i believe that sub-sub-sections such as configuration basics, networking basics, authenticationa and user basics would need more content which would invariably help a user/developer if applied.

Could the present documentation be redistributed more evenly across the quadrants? How so? The present documentation can be redistributed more evenly across the different quadrants by following the diataxis framework which answers to a different user need, fulfils a different purpose and requires a different approach to its creation. We could use the diataxis framework to bring more clarity by paying even more attention to the needs of our users by rewriting our present documentation in such a way that areas which are learning-oriented such that it takes a reader by the hand through a series of steps to complete a project are categorized under “Tutorials” quadrant, also, areas in our documentation which primarily take readers through the steps required to solve real-world problems are categorized in the “How-to-guides” quadrant, areas in our documentation that focuses on information, alongside technical machinery and how to operate it are categorized in the “Reference” quadrant and lastly, areas in our documentation which primarily clarifies and illuminates a particular topic should be categorized under the “Explantion” quadrant.

Did you find a particular page that could be improved or changed? What would you like to see happen that would improve it? The page i think could be improved or changed is this. I would like to see a more robust overview of what the RBAC framework is and the problem it solves. I’ll also like for the “Upgrade steps” to be succintly written to help newbies easily understand. Also, i think the explanation on the ‘OAuth vs API tokens” should come immediately after the RBAC framework is introduced at the start of the page in other for readers to have more context and get answers to why they need to upgrade jupyterhub with the RBAC framework.

[softkeldozy]

a) Judging by the framework given the current state of the documentation is a little bit confusing and could use some restructuring. The state of the documentation right now is not going to be friendly to someone new to JupyterHub. b) Technical Reference c) Yes, it can. Take for instance the "Setting up a Development Install" found inside the "Contributing page" which can be taken to the "Installation page" which can be categorized under the Tutorial quadrant. d) The contribution page is not that specific and can be changed to fit its name. I would like to see most items there categorized and placed how they fit in the quadrant, enhancing how the page is structured. The contribution page should be about community and improving JupyterHub.

[sgibson91]

Update

This microtask will be closed to new applicants on Monday 24th October (end of day UK time).

Please make sure your contributions are recorded and begin your final application on the Outreachy website. If your issue/PR is still open when we close this project, it will still count as a contribution. Closing the project will not affect your ability to record contributions and make your final applications.

[Jaykold]

Update

This microtask will be closed to new applicants on Monday 24th October (end of day UK time).

Please make sure your contributions are recorded and begin your final application on the Outreachy website. If your issue/PR is still open when we close this project, it will still count as a contribution. Closing the project will not affect your ability to record contributions and make your final applications.

Can we make a final application without our contribution being merged?

[sgibson91]

Can we make a final application without our contribution being merged?

Yes

[softkeldozy]

a) The current state of the document is a little bit close to its desired purpose but needs a little adjustment for it to align with the Diataxis Framework. b)Technical Reference d) The "Configuration Examples" subset under the Technical Reference page has its sublinks outside of its enclosing body (being the Configuration Examples), these links need to be a sublink of the "Configuration Examples" page just like the others on the page.