Difference between revisions of "Documentation improvement initiative"
(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 | ||
|- | |- | ||
| − | | | + | | 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 [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 | 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 |
