Documentation Improvement Initiative

[David Gileadi]

On 5/5/20 10:25 PM, WebFreak001 wrote:
> On Wednesday, 6 May 2020 at 02:34:33 UTC, Mike Parker wrote:
>> On Tuesday, 5 May 2020 at 16:05:44 UTC, Jan Hönig wrote:
>>> On Sunday, 3 May 2020 at 07:35:03 UTC, Jan Hönig wrote:
>>>> - Encourage newcomers to edit the wiki. This is a simple task, often 
>>>> dull to do for experienced community members, but great for 
>>>> newcomers, because they are included AND they explore the wiki ant 
>>>> the community on themselves.
>>>
>>> I felt encouraged today, so I created this list[1]
>>> I hope it was OK.
>>>
>>> Please feel free to fill, sort & enhance.
>>>
>>>
>>> [1]: https://wiki.dlang.org/Documentation_improvement_initiative
>>
>> Thanks!
>>
>> I'm still looking for documentation tasks that require enough work 
>> that we can use them for the event. Adding one or two lines here or 
>> there isn't enough. And something that requires weeks is too much. 
>> We're looking for things that can be accomplished in terms of hours or 
>> days.
> 
> How about also cleaning up documentation how it looks on the web? Like 
> missing macros are rendered blank in ddox, so the usage or the 
> definition could get fixed. Example missing something: 
> https://vibed.org/api/vibe.db.mongo.mongo/ (ending with "a dedicated 
> utility for this called .", missing the $(LINK2 ...) macro)
> 
> ddox also doesn't support showing mixin templates yet, which are however 
> already reported in the JSON by the dmd documentation generator thing 
> and only need some implementation.
> 
> Also something I'm finding essential and think should be added to the 
> DDoc spec: $(LREF) and $(REF) - they are used a lot in phobos and (a bit 
> biased) they are also implemented in the code-d doc preview / code tips 
> already for all packages, making them look nicely already there. Even if 
> it just suggests that these are subject to implementation for each 
> documentation generator, having a well defined syntax and explanation 
> would help a lot.

Incidentally in my -preview=markdown changes putting a symbol in 
brackets (using Markdown syntax for a link) like [string] creates a link 
to that symbol's definition [1]. I suspect my implementation isn't 
perfect, but like the rest of the -preview=markdown changes my hope is 
that it makes the docs easier to write.

[1]: https://dlang.org/spec/ddoc.html#reference_links