On Tuesday, 5 January 2016 at 18:09:57 UTC, Andrei Alexandrescu wrote:
On 01/05/2016 11:35 AM, default0 wrote:

Yes, and because its lots of effort flowing into something that D is
usually very fond of: Simplicity.

I'll be curious how the simplicity theme keeps when needed features get added. dlang.org started very simple and grew by accretion.

From Adam's responses it would seem he is going to ignore most of the features the original dlang.org has in favor of focussing on HTML documentation.

I remember looking at a part of the documentation and wanting to suggest a change of wording in a few sentences, since I felt like they didn't convey information clear enough, but after seeing that I would have to somehow best-guess my way through tons of macro syntax without clear indication on where to look for explanations of anything I bailed. Not about to spend half a day or a day to suggest changing three sentences
and be told that they were fine as is.

Is the recent http://wiki.dlang.org/Contributing_to_dlang.org along the lines of what you need? What other sort of documentation would you find useful?

Yes, this is helpful in providing background on how to make changes. That said, the amount of content on this page is telling that it'll be an involved process to set stuff up, especially if at some point in my setup I get errors that are neither explained nor straightforward to track down. So while this is helpful, it also makes it clear that there's a not-low barrier to entry if I do want to introduce a change - which is fine, except if it's documentation that barrier to entry should be actually formulating coherent, understandable and thorough documentation rather than a build system.

Sending Adam an E-Mail is
something I totally would've done though :-)

Again this goes back to Adam. Let's say we had a contributor Eve who'd gladly take emailed questions and suggestions and integrate them. Would that be as nice?


Much nicer than reading a somewhat long page on how to set up a new development environment and fiddling with it until it does what I want, followed by trying to guess what macros I need to invoke for displaying what things, followed by checking if it renders as expected or if I accidentally used a "," incorrectly somewhere instead of just formulating a documentation text that is hopefully an improvement over what existed prior to it (or filling a void that used to be there) :-)

In the end most of this comes down to a lack of motivation: I'm fine trying to improve documentation text if I see an issue about it, but if that entails stopping what I was originally doing for so long that I will possibly forget what I was originally doing (ie requires me to read documentation on how to set up a whole new development environment), I will usually decide that nah, it isn't THAT important.

While I could obviously reuse the setup after I did it once, I'm not keen on doing it once, I do happen to be a really lazy person about setting things up (not so much doing actual work on something that is already set up, though) because I tend to get really weird errors for really weird reasons when trying to (not in particular with D - I just always seem to be doing everything wrong when setting anything up).

Reply via email to