www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - New DUB documentation

reply WebFreak001 <d.forum webfreak.org> writes:
the revamped DUB documentation I started a while ago is now 
deployed on https://dub.pm

A bunch of pages are still WIP, but the already done pages have a 
bunch of new information and should be better structured. I 
recommend giving the new documentation a try, maybe you will 
learn something new about DUB.

If you find anything to edit, the "Edit this Page" button makes 
it trivially easy - it's all standard markdown files now that are 
easily editable.

If you previously often looked at the recipe page that contained 
all the information in a single page, you will find most of the 
information on https://dub.pm/dub-reference/build_settings/ now 
and there are even more details on separate pages now.

The site's built-in search on the page works great and runs fully 
offline, try it out! It will find your search across the entire 
documentation. CLI documentation is now also included more 
similar to the man page format here.
Nov 22 2023
next sibling parent reply claptrap <clap trap.com> writes:
On Wednesday, 22 November 2023 at 21:35:34 UTC, WebFreak001 wrote:

 the revamped DUB documentation I started a while ago is now 
 deployed on https://dub.pm

 A bunch of pages are still WIP, but the already done pages have 
 a bunch of new information and should be better structured. I 
 recommend giving the new documentation a try, maybe you will 
 learn something new about DUB.

 If you find anything to edit, the "Edit this Page" button makes 
 it trivially easy - it's all standard markdown files now that 
 are easily editable.

 If you previously often looked at the recipe page that 
 contained all the information in a single page, you will find 
 most of the information on 
 https://dub.pm/dub-reference/build_settings/ now and there are 
 even more details on separate pages now.

 The site's built-in search on the page works great and runs 
 fully offline, try it out! It will find your search across the 
 entire documentation. CLI documentation is now also included 
 more similar to the man page format here.


IMO you have to many menus, you have menu bar across the top, 
left side menu, right side menu. So it's like you need to grep 
all three of them and how the are related to work out where you 
are.

A single table of contents type menu would be better IMO, a left 
sidebar that gives links to all the pages. It would make it a lot 
easier to understand where you are in the overall structure of 
the guide.
Nov 22 2023
next sibling parent reply Vladimir Marchevsky <vladimmi gmail.com> writes:
On Wednesday, 22 November 2023 at 21:52:12 UTC, claptrap wrote:

 A single table of contents type menu would be better IMO, a 
 left sidebar that gives links to all the pages.


Wouldn't it be too huge? 5 big separate sections, each has a list 
of articles, each article having a number of chapters, 
sub-chapters, sub-sub-chapters...
Nov 22 2023
parent "H. S. Teoh" <hsteoh qfbox.info> writes:
On Wed, Nov 22, 2023 at 09:58:51PM +0000, Vladimir Marchevsky via
Digitalmars-d-announce wrote:

 On Wednesday, 22 November 2023 at 21:52:12 UTC, claptrap wrote:

 A single table of contents type menu would be better IMO, a left
 sidebar that gives links to all the pages.


 
 Wouldn't it be too huge? 5 big separate sections, each has a list of
 articles, each article having a number of chapters, sub-chapters,
 sub-sub-chapters...


Could be optionally expanded depending on where you are in the
navigation.


T

-- 
Never criticize a man until you've walked a mile in his shoes. Then when you do
criticize him, you'll be a mile away and he won't have his shoes.
Nov 22 2023
prev sibling parent reply WebFreak001 <d.forum webfreak.org> writes:
On Wednesday, 22 November 2023 at 21:52:12 UTC, claptrap wrote:

 On Wednesday, 22 November 2023 at 21:35:34 UTC, WebFreak001 
 wrote:

 [...]


 IMO you have to many menus, you have menu bar across the top, 
 left side menu, right side menu. So it's like you need to grep 
 all three of them and how the are related to work out where you 
 are.

 A single table of contents type menu would be better IMO, a 
 left sidebar that gives links to all the pages. It would make 
 it a lot easier to understand where you are in the overall 
 structure of the guide.


the layout is standard from material for mkdocs and widely used 
in other projects, no plans on changing that for now, the 
experience is more efficient for when you get used to it too.
Nov 22 2023
parent notna <notna.remove.this ist-einmalig.de> writes:
On Thursday, 23 November 2023 at 07:16:59 UTC, WebFreak001 wrote:

 the layout is standard from material for mkdocs and widely used 
 in other projects, no plans on changing that for now, the 
 experience is more efficient for when you get used to it too.


a BIG thanks for the re-work from my side.

I personally do like the new docu and layout.... and the smart 
move to `mkdocs` because it's the most used technical 
documentation framework out there __AND__ now many more people 
can easily enhance / improve things...
Nov 24 2023
prev sibling next sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Wednesday, 22 November 2023 at 21:35:34 UTC, WebFreak001 wrote:

 the revamped DUB documentation I started a while ago is now 
 deployed on https://dub.pm


This is very much appreciated. A job well done!

-- Bastiaan.
Nov 23 2023
parent reply BoQsc <vaidas.boqsc gmail.com> writes:
The new DUB documentation feels less efficient for use. First 
impression: headache.

If the content is improved and refined, then yeah that's 
welcoming, a good thing and well done.

But overall use, it just feels like trying to be modern without 
being clever and usable.

I think the previous design was better, more user-friendly, even 
if looked worse.

Darker blending indistinct colors (dark red, dark background), 
way smaller fonts.
![](https://i.imgur.com/2p0bk70.png)


Gray headers on gray background.
![](https://i.imgur.com/STpd64a.png)

The link colors are giving headaches too. But that might be only 
for me right now.
Nov 24 2023
next sibling parent reply BoQsc <vaidas.boqsc gmail.com> writes:
Also it's a good idea to maintain the same style as dlang forum 
and dlang website, along with dlang tour and online dlang editor. 
The dlang webdesign choice feels really solid and robust. At 
least from my perspective.

If someone needed a dark theme dub documentation. A simple button 
to toggle it would have been enough.

Small tweaks for layout and small tweaks overall for more 
professional look and efficiency of use. Would have been enough.
Nov 24 2023
parent WebFreak001 <d.forum webfreak.org> writes:
On Friday, 24 November 2023 at 11:32:18 UTC, BoQsc wrote:

 Also it's a good idea to maintain the same style as dlang forum 
 and dlang website, along with dlang tour and online dlang 
 editor. The dlang webdesign choice feels really solid and 
 robust. At least from my perspective.

 If someone needed a dark theme dub documentation. A simple 
 button to toggle it would have been enough.

 Small tweaks for layout and small tweaks overall for more 
 professional look and efficiency of use. Would have been enough.


I don't know what you are talking about? The dark theme is just a 
single button press and the default is light theme which is very 
similar to the dlang page (unless you have changed your system 
theme to dark theme, it uses the browsers preference, if any)

The dub docs are hosted on https://github.com/dlang/dub-docs, you 
can PR CSS changes there if you want to change the link color in 
dark theme. (I don't really use dark theme so I never looked at 
it too much, it came in as a contribution)
Nov 28 2023
prev sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Friday, 24 November 2023 at 11:11:53 UTC, BoQsc wrote:

 Darker blending indistinct colors (dark red, dark background), 
 way smaller fonts.


I see your screenshots, but that is not what it looks like for me 
in Chrome on Windows. I am seeing black text on white background 
with red links. Pretty much like the rest of the D web ux. Is 
there a dark theme you have enabled?

The font does look slightly smaller, though.

-- Bastiaan.
Nov 27 2023
parent WebFreak001 <d.forum webfreak.org> writes:
On Monday, 27 November 2023 at 13:25:20 UTC, Bastiaan Veelo wrote:

 On Friday, 24 November 2023 at 11:11:53 UTC, BoQsc wrote:

 Darker blending indistinct colors (dark red, dark background), 
 way smaller fonts.


 I see your screenshots, but that is not what it looks like for 
 me in Chrome on Windows. I am seeing black text on white 
 background with red links. Pretty much like the rest of the D 
 web ux. Is there a dark theme you have enabled?

 The font does look slightly smaller, though.

 -- Bastiaan.


the button next to the search bar toggles between light and dark 
theme:

![theme switcher button screenshot](https://wfr.moe/f6McOo.png)
Nov 28 2023
prev sibling next sibling parent Guillaume Piolat <first.name gmail.com> writes:
On Wednesday, 22 November 2023 at 21:35:34 UTC, WebFreak001 wrote:

 the revamped DUB documentation I started a while ago is now 
 deployed on https://dub.pm


Thanks for this!
Nov 24 2023
prev sibling next sibling parent bachmeier <no spam.net> writes:
On Wednesday, 22 November 2023 at 21:35:34 UTC, WebFreak001 wrote:

 the revamped DUB documentation I started a while ago is now 
 deployed on https://dub.pm


Limiting my comments to the "Getting Started" page, since that's 
obviously where new programmers will go first.

On the very first page, there are links to the DUB registry 
website and assorted man pages. You've just lost half the 
audience right there. The best possible outcome is that the user 
is confused but pushes on. It says "You can also skip ahead to 
First steps if you already have dub installed." How do they know 
if it's installed?

The first page has to be crystal clear. It can't have 
distractions or require knowledge of the installation status of 
this thing called "DUB".

The "First Steps" page is likely to be the last steps for many. 
It provides a CLI command and then shows a bunch of output from 
an interactive session with no explanation. That's followed by a 
brief discussion of directories and files. There's also mention 
of .gitignore, so I guess that means Git is required to use DUB. 
Then there's discussion of two formats, with no information on 
how to choose, or why it's important. That's followed by a 
presentation of configuration files with no explanation.

I wish I could be positive, but this doesn't move the needle. The 
two key ingredients for a getting started guide are examples and 
explanations, and both are missing.
Nov 24 2023
prev sibling parent reply Mike Shah <mshah.475 gmail.com> writes:
On Wednesday, 22 November 2023 at 21:35:34 UTC, WebFreak001 wrote:

 the revamped DUB documentation I started a while ago is now 
 deployed on https://dub.pm

 [...]


Just wanted to say that I appreciate the effort and improvements 
to the documentation. The ability to easily edit and add new 
examples will be incredibly useful over time.
Nov 27 2023
parent jmh530 <john.michael.hall gmail.com> writes:
On Monday, 27 November 2023 at 16:08:09 UTC, Mike Shah wrote:

 On Wednesday, 22 November 2023 at 21:35:34 UTC, WebFreak001 
 wrote:

 the revamped DUB documentation I started a while ago is now 
 deployed on https://dub.pm

 [...]


 Just wanted to say that I appreciate the effort and 
 improvements to the documentation. The ability to easily edit 
 and add new examples will be incredibly useful over time.


Ditto. Even where people have suggestions for further 
enhancements, I very much appreciate the work done here.
Nov 27 2023