www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - Call for action: Easily improve D's ecosystem - DUB documentation

reply WebFreak001 <d.forum webfreak.org> writes:
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:



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.



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](https://github.com/WebFreak001/dub-docs-v2) for 
more details



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.



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.



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.



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 


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!)


right now :D
Nov 14 2022
next sibling parent WebFreak001 <d.forum webfreak.org> writes:
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.
Nov 14 2022
prev sibling next sibling parent rikki cattermole <rikki cattermole.co.nz> writes:
I've filled in some details about shared libraries wrt. plugins the 
issue for it.

Will need compiler specific information CC: Walter, Martin, Iain.

Still massive shame that dmd is still a write off for Windows support 
when using D from D. Wahoo export + ModuleInfo + DLLs.

Oh and don't forget about the no Unicode exported on Windows!
Nov 14 2022
prev sibling parent reply WebFreak001 <d.forum webfreak.org> writes:
bump (for email readers, URL of this thread: 
https://forum.dlang.org/post/ojoiwbcftqsxbsvivghz forum.dlang.org)

- added some new pages with new content
- github issues still contain information for contributors that 
want to help improving the documentation
- on https://docs.webfreak.org it now shows links to the issues 
with content hints and suggestions on each page, so that you can 
easily find pages to work on
Sep 01 2023
parent WebFreak001 <d.forum webfreak.org> writes:
On Friday, 1 September 2023 at 11:52:18 UTC, WebFreak001 wrote:

 bump (for email readers, URL of this thread: 
 https://forum.dlang.org/post/ojoiwbcftqsxbsvivghz forum.dlang.org)

 - added some new pages with new content
 - github issues still contain information for contributors that 
 want to help improving the documentation
 - on https://docs.webfreak.org it now shows links to the issues 
 with content hints and suggestions on each page, so that you 
 can easily find pages to work on


now PR to make it official for dub.pm: 
https://github.com/dlang/dub-docs/pull/54
Sep 01 2023