Documentation Improvement Initiative

[WebFreak001]

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.