Difference between revisions of "Documentation improvement initiative"

From D Wiki
Jump to: navigation, search
 
(4 intermediate revisions by 2 users not shown)
Line 10: Line 10:
 
| 1 ||promote wiki.dlang.org directly on D's webpage
 
| 1 ||promote wiki.dlang.org directly on D's webpage
 
|-
 
|-
| 1b||abandon the wiki, transfer the content to github
+
| 1b||abandon the wiki, transfer the content to github|| github's wiki does not have PRs. collaboration is thus not trivial
 
|-
 
|-
 
| 2 ||encourage authors to copy/write/(at least link) articles/tutorials/cookbooks on the wiki || many articles/tutorials/cookbooks exist on the wiki, but also many are scattered threw out the web
 
| 2 ||encourage authors to copy/write/(at least link) articles/tutorials/cookbooks on the wiki || many articles/tutorials/cookbooks exist on the wiki, but also many are scattered threw out the web
Line 24: Line 24:
 
| 7 ||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 and the community on themselves.
 
| 7 ||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 and the community on themselves.
 
|-
 
|-
| 8 ||Finish the book https://github.com/PhilippeSigaud/D-templates-tutorial
+
| 8 ||Finish the [https://github.com/PhilippeSigaud/D-templates-tutorial template book]||There is no license yet
 
|-
 
|-
| 9 ||declare unmaintained and broken packages as such
+
| 9 ||declare unmaintained and broken packages as such || maybe flag / comment (/ vote) system like on the Arch User Repository?
 
|-
 
|-
 
|10||document -preview, make a timeline for those changes, document them e.g. per switch in a github issue (like bazel does)
 
|10||document -preview, make a timeline for those changes, document them e.g. per switch in a github issue (like bazel does)
Line 32: Line 32:
 
|11||better docs for simd. How do I add new opcodes, if I miss one? Tutorials.
 
|11||better docs for simd. How do I add new opcodes, if I miss one? Tutorials.
 
|-
 
|-
|12||better docs for dub, subpackages, examples, recommended project layouts
+
|12||<del>better docs for dub, subpackages, examples, recommended project layouts</del> || See https://dub.pm
 
|-
 
|-
 
|13||better docs/tutorials for the mir libraries
 
|13||better docs/tutorials for the mir libraries
 
|-
 
|-
 
|14||comprehensive guide to memory management with comparison of std.allocator / GC / automem(?) || show idiomatic usage of these
 
|14||comprehensive guide to memory management with comparison of std.allocator / GC / automem(?) || show idiomatic usage of these
 +
|-
 +
|15||officially document $(REF), $(LREF) || REF and LREF are commonly used in phobos for reference other symbols for jumping to documentation. Having specified syntax for documentation generators to implement would help discover and implement this.
 +
|-
 +
|16||improve how public facing documentation (web documentation) looks in projects || fix missing/broken macros (e.g. rendered blank in ddox)
 +
|-
 +
|16b||improve ddox || implement showing mixin templates as members, which are currently simply not shown but already passed from dmd
 
|}
 
|}

Latest revision as of 10:39, 25 June 2020

This is an unsorted list of tasks, which improve the documentation. The original thread on the forum can be found here.

The List

Id Description Info / Guides / People working on
1 promote wiki.dlang.org directly on D's webpage
1b abandon the wiki, transfer the content to github github's wiki does not have PRs. collaboration is thus not trivial
2 encourage authors to copy/write/(at least link) articles/tutorials/cookbooks on the wiki many articles/tutorials/cookbooks exist on the wiki, but also many are scattered threw out the web
3 on code.dlang.org decrease score of packages, which don't build
4 Link tutorials or cookbooks in language and library reference Existing examples are simple and clear. A newcomer needs also more complex examples, like tutorials or cookbooks. Use only one link in documentation to avoid clutter.
5 opinionated suggestions in getting started https://wiki.dlang.org/Getting_Started a newcomer is overwhelmed by the possibilities of compilers,editors/ides; Suggestions: dmd, vscodium with code-d
6 pack this task list somewhere on the wiki done
7 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 and the community on themselves.
8 Finish the template book There is no license yet
9 declare unmaintained and broken packages as such maybe flag / comment (/ vote) system like on the Arch User Repository?
10 document -preview, make a timeline for those changes, document them e.g. per switch in a github issue (like bazel does)
11 better docs for simd. How do I add new opcodes, if I miss one? Tutorials.
12 better docs for dub, subpackages, examples, recommended project layouts See https://dub.pm
13 better docs/tutorials for the mir libraries
14 comprehensive guide to memory management with comparison of std.allocator / GC / automem(?) show idiomatic usage of these
15 officially document $(REF), $(LREF) REF and LREF are commonly used in phobos for reference other symbols for jumping to documentation. Having specified syntax for documentation generators to implement would help discover and implement this.
16 improve how public facing documentation (web documentation) looks in projects fix missing/broken macros (e.g. rendered blank in ddox)
16b improve ddox implement showing mixin templates as members, which are currently simply not shown but already passed from dmd