Difference between revisions of "Documentation improvement initiative"

From D Wiki
Jump to: navigation, search
(Created page with "This is an unsorted list of tasks, which improve the documentation. The original thread on the forum can be found [https://forum.dlang.org/post/xqovfyklaxjmxxhpdwdx@forum.dlan...")
 
 
(10 intermediate revisions by 3 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
 
|-
 
|-
| 2 ||promote authors to copy/write/(at least link) articles/tutorials/cookbooks on the wiki (there are many, but also many are scattered threw out the web)
+
| 1b||abandon the wiki, transfer the content to github|| github's wiki does not have PRs. collaboration is thus not trivial
 
|-
 
|-
| 3 ||decrease score of packages, which don't build on code.dlang.org
+
| 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
 
|-
 
|-
| 4 ||Language and library reference have enough examples (at least the parts I use). Examples are simple and clear. However to a newcomer needs also more complex examples, like tutorials or cookbooks. Idea: one link, on the specific reference to a section with related articles/tutorials/cookbooks.
+
| 3 ||on code.dlang.org decrease score of packages, which don't build
 
|-
 
|-
| 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)
+
| 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.
 
|-
 
|-
| 6 ||probably pack this task list somewhere on the wiki || done
+
| 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
 
|-
 
|-
| 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 ant the community on themselves.
+
| 6 ||pack this task list somewhere on the wiki || done
 
|-
 
|-
| 8 ||Finish the book https://github.com/PhilippeSigaud/D-templates-tutorial
+
| 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 [https://github.com/PhilippeSigaud/D-templates-tutorial 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||<del>better docs for dub, subpackages, examples, recommended project layouts</del> || 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
 
|}
 
|}

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