Call for action: Easily improve D's ecosystem - DUB documentation improvements

November 15, 2022

Posted by WebFreak001

Permalink

WebFreak001

Permalink

Hello everyone,

I have been working on revamped DUB docs, which should help users with adoption of D, with DUB being basically the package manager everyone uses. I have deployed the current state here:

https://docs.webfreak.org/

However a lot of pages are still empty and this is quite a bunch of work writing. I don't think it's best if only one person looks over all of this, so I'm looking for feedback from the community. Here is how you can help:

Read the docs

Open as many issues as you need about any misunderstandings you have or submit PRs for typos.

There are quite a lot of pages already, they were all written with varying quality, so fact-checking, proof-reading and quality control would be very much appreciated here. (especially for things that have been written at 3 AM)

You could even learn new things about DUB quite easily here! The docs currently cover all the source code.dlang.org content + lots of additional in-depth information that you would usually only get by reading the source code or trying things out a lot.

Write the docs

Check out the issues: https://github.com/WebFreak001/dub-docs-v2/issues

A lot of pages, or parts of pages, might be quite trivial to regular dub users, so I would love if any of you out there could help write pages here.

Here is how you can write docs:

(Basic) you can just edit the markdown files and optionally also view them with any markdown viewer of your choice, this might not work that well for recipe content or code examples though.
(Advanced) if you have Python3 installed, you can build the Markdown docs into the nice HTML website you can see hosted above. Basically you just install the dependencies and can then run mkdocs serve to have an auto-reloading page whenever you make edits. This is a very comfortable way to write docs. See project README for more details

Make things clearer

No text is perfect, a lot of this is also written in bulk, with relatively quick typing and at times not too much thinking. If you spot anything that is unclear or could be better with a rewording, feel free to open an issue or make a PR.

Completing content

Like above, if you spot anything that is missing or incomplete, feel free to write the docs immediately or write parts of them and open a PR with them. You might also just wanna comment on the issues on GitHub with what other ideas you have to put on each page or make your own issues for larger things.

Voting on what to work on

If you don't have the time to work on documentation, I would appreciate if you could at least take a minute to vote for your favorite content on GitHub. There are issues for nearly each page on GitHub already, just react to the opening post with a thumbs up, to give it more visibility in the search sorting. (when applied) - If you have another minute, don't forget to write what especially you want to see or what to see changed!

For bigger things, feel free to open your own issues as well.

Outlining

A lot of documents are still completely empty. I have made issues on GitHub to describe what I thought could be put on each page, but haven't yet put any headers or content on most of these pages. If you want to help decide on what goes on the page, feel free to just add markdown headings (# Page title, ## Subtitle 1, ### Subtitle 2) to create empty skeletons for anyone to write in it. I think this is quite a low effort thing to work on, that's however very useful to give ideas how the content could look like and be structured.

Even if you have only a very basic understanding of DUB, there is a good chance there are still empty sections you can fill with your knowledge - check the issues. Each issues has a list of bullet-points that would probably be a good idea to be put in the document. In the smallest increments you could for example add anywhere from only a single bullet point at a time or a full document all at once.

Usually more content is better for this brainstorming and writing phase, we can always remove or summarize unnecessary / duplicate content in the future.

I hope there are some of you out there who can help with this project, I think this project is quite an important, but not that overly complex, task that many people here can help with.

I think this is quite a low risk, high return thing to be working on, which just still needs a bunch of work to be doing.

So, because you made it this far into the post - first of all thank you for taking the time to read this and any interest you may have.

Here are the links again that you might be interested in:

Issues, sorted by most thumbs up: https://github.com/WebFreak001/dub-docs-v2/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc
Repository: https://github.com/WebFreak001/dub-docs-v2
Current docs preview: https://docs.webfreak.org/
Reference to the docs theme I'm using: https://squidfunk.github.io/mkdocs-material/reference/ (there are cool widgets and formatting tips in here that could be used if needed!)

also don't judge me for errors in this post, it's 4 AM right now :D

Additional things that are quite low priority, but might be interesting for anyone who is looking to contribute on the tech side:

auto-testing what's written in the docs is probably a good idea. Ideally by extracting the markdown, but not required. Should test whole dub packages
D source code could be validated for syntax and output (e.g. using https://code.dlang.org/packages/md)
auto-deployment is still missing, GitHub pages and actions could be used with this (especially interesting for PRs)
dead link detection is probably gonna be useful soon (awesome-dlang has a GitHub actions workflow for this, could reuse that)
"Run in online IDE" button for code using run.dlang.io would be useful - can use single file packages there.